home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / UTIL / SYS / ARCTOOLS / !ArcTools / Manual < prev    next >
Text File  |  1992-10-28  |  150KB  |  4,054 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.    AAAAAAAA  RRRRRRR  CCCCCCC TTTTTTTTTT  OOOOOO    OOOOOO  LL      SSSSS
  10.    AA    AA  R     R  CC   CC T   TT   T OO    OO  OO    OO LL     SS   S
  11.    AAAAAAAA  RRRRRRR  CC          TT     OO    OO  OO    OO LL     SS
  12.    AA    AA  R  RR    CC          TT     OO    OO  OO    OO LL      SSSS 
  13.    AA    AA  R  RR    CC          TT     OO    OO  OO    OO LL         SS
  14.    AA    AA  R   RR   CC   CC     TT     OO    OO  OO    OO LL     S   SS
  15.    AA    AA  R    RR  CCCCCCC    TTTT     OOOOOO    OOOOOO  LLLLLL SSSSS 
  16.  
  17.  
  18.  
  19.  
  20.                               Version  0.72
  21.  
  22.  
  23.                 Written by:  Mohsen Alshayef  27 Oct 1992
  24.  
  25.                   Copyright (C)  Mohsen Alshayef 1992
  26.  
  27.  
  28.  
  29.  
  30.             *************************************************
  31.             *   This version of ARCTOOLS is Public Domain   *
  32.             *************************************************
  33.  
  34.  
  35.  
  36.  
  37.  ARCTOOLS is a complex program which is under continuous development and,
  38.  while every effort is made to ensure it functions as detailed in this
  39.  manual, I cannot accept any liability for any loss or damage resulting
  40.  from the use of ARCTOOLS or the information in this manual.
  41.  
  42.  
  43.  
  44.                 *****************************************
  45.                 *   For further information contact:    *
  46.                 *                                       *
  47.                 *     Mohsen Alshayef,                  *
  48.                 *     PO BOX 50217,                     *
  49.                 *     AL-Hidd,                          *
  50.                 *     Bahrain,                          *
  51.                 *****************************************                                        
  52.  
  53.  
  54.  
  55.  
  56. Manual contents
  57. ===============
  58.   Introduction:
  59.       Important Notice
  60.       System Requirements
  61.       Starting ARCTOOLS
  62.  
  63.   The *Commands:
  64.       Commands summary
  65.       Disc and file commands
  66.       Memory commands
  67.       General commands
  68.  
  69.   The memory editors
  70.  
  71.   The disc editors:
  72.       Using the disc editors with non-standard discs.
  73.       Recovering deleted files using the disc editors.
  74.  
  75.   The Commands Menu
  76.  
  77.   Keys used in the editors:
  78.       Keys summary
  79.       Keys discription
  80.  
  81.   The dis-assembler
  82.  
  83.   The single-line assembler
  84.  
  85.   Calling the assembler from BASIC
  86.  
  87.   Using the dis-assembler to recover lost ARM code source files
  88.  
  89.   ARM 3 instructions assembly and disassembly
  90.  
  91.  
  92.                      *****************************
  93.                      *       Introduction        *
  94.                      *****************************
  95.  
  96. ARCTOOLS is a utility module which adds many *Commands that most of you
  97. will find very valuable.Some are seldom used, but they are there when you
  98. need them. ARCTOOLS tries to add commands that are valuable to users
  99. (beginners and experienced) as well as facilities that many advanced
  100. ARM code programmers need.
  101.  
  102. ARCTOOLS differs from other utility modules in that most of its commands
  103. are accessible from within the various memory and disc editors. An area
  104. of memory or disc can be marked and then various operations can be
  105. performed on it using a simple and efficient menu system.
  106. ARCTOOLS also provides many facilities built into its editors with the
  107. promise of more in future vesrions.
  108.  
  109. ARCTOOLS is not a multi-tasking application. Speed and ease of use is
  110. what all matters to real users of ARCTOOLS. Fast scrolling colourful
  111. text in the mnemonic or dis-assembler with automatic search for defined
  112. labels every time an instruction is decoded out of memory has to be
  113. done with no delays. This, however, does not mean that I am not thinking
  114. of a Desktop version. ARCTOOLS has a built in 'Commands' menu, accessible
  115. from any disc or memory editor. With few simple key strokes you can achieve
  116. what takes ages with the mouse. Experienced users always use keyboard
  117. shortcuts in any application.
  118.  
  119. The number of *Commands provided will be extended in the future.
  120. Please feel free to contact me on the address given above if you need a
  121. customized version with say certain *Commands added or others removed or
  122. you want different keys to be used in the different editors.
  123. Also, if you have any suggestions, comments, bugs discovered etc., I will
  124. be pleased to here from you.
  125. If you have a utility that YOU have written or an idea of a utility, please
  126. contact me, I'll be happy to add your code to your customized ARCTOOLS.
  127.  
  128. ARCTOOLS is in a continuous development. New versions are coming up in every
  129. two to three weeks, so please send suggestions and comments.
  130.  
  131.                       ****************************
  132.                       *    Important Notice      *
  133.                       ****************************
  134.  
  135. It is the user's responsibility to ensure that ARCTOOLS is used lawfully
  136. and you are not permitted to use it in violation of Copyright Law.
  137.  
  138. You may NOT change ARCTOOLS utility or use ANY part of it in other products
  139. without my approval. You may spread it freely with ALL files included,
  140. but not for any profit. This software is provided 'as is'. Using it is
  141. entirely at your own risk.
  142.  
  143. You are not allowed to distribute ARCTOOLS as an 'extra' in any commercial
  144. product.
  145. This version of ARCTOOLS is public domain. Future versions will remain
  146. public domain until I decide otherwise.
  147. If you are interested in ARCTOOLS as a commercial product, you are kindly
  148. invited to contact me to discuss financial details. 
  149.  
  150.                        *************************
  151.                        *  System Requirements  *
  152.                        *************************
  153.  
  154. ARCTOOLS has been assembled using the BBC BASIC assembler and the ARM
  155. BASIC EDITOR on an A5000 with 4 M bytes of memory and 120 M bytes Hard
  156. Disc under RISC OS 3.10.
  157.  
  158. ARCTOOLS requires RISC OS 3 or higher to run. You may find that some
  159. of ARCTOOLS commands will work on RISC OS 2 systems, but the memory
  160. and disc editors will not. ARCTOOLS uses some of the new RISC OS 3
  161. SWIs.
  162.  
  163.  
  164.  
  165.  
  166.                         ***********************
  167.                         *  Starting ARCTOOLS  *
  168.                         ***********************
  169.  
  170. ARCTOOLS can be loaded into your system (as a module):
  171.  
  172.  1. From the Desktop: Click twice on the ARCTOOLS icon.
  173.  2. From the line command: type  *ARCTOOLS
  174.  
  175. ARCTOOLS will take 63 K bytes from the RMA for its code and 39 K bytes
  176. for its workspace. Additionally it will claim 32 Kbytes for the labels
  177. buffers.
  178.  
  179. Future versions of ARCTOOLS will allow the user to specify the size of
  180. the different ARCTOOLS buffers.
  181.  
  182.  
  183.  
  184.  
  185.                            ARCTOOLS *Commands
  186.                            ==================
  187.  
  188. Using the *Commands:
  189. ====================
  190.  
  191. ARCTOOLS provides three categories of *command:
  192. - Disc and file commands.
  193. - Memory commands.
  194. - General commands.
  195.  
  196. To issue *Commands from wihin the desktop: press F12 and then type the
  197. required command.
  198.  
  199. To enter any of the disc or memory editors from within the desktop you
  200. should use the command line by pressing F12. Do not use the task window.
  201. The memory and disc editors use direct screen access and will mess up the
  202. desktop windows if entered from the task window.
  203.  
  204.  
  205. *Commands summary:
  206. ==================
  207.  
  208.  1: *BList <filename> [<line number>][,[<line number>]] [<LISTO number>]
  209.  2: *Clear <start> <end>|+<length>
  210.  3: *Dedit <drive> [<address>] [<format>]
  211.  4: *Dget <drive> <disc addrs> <end>|+<length> <memory addrs>
  212.  5: *DLock [<ON|OFF>]
  213.  6: *DMap [<drive>]
  214.  7: *Dput <drive> <memory addrs> <end>|+<length> <disc addrs>
  215.  8: *Event [<event number> <ON|OFF>]
  216.  9: *Fcompare <1st file> <2nd file> [<max diff>]
  217. 10: *Fcount <filename> <string> [C]
  218. 11: *Fdump <filename> <format> [<offset>]
  219. 12: *Files 
  220. 13: *FillH <start> <end>|+<length> <Hex list>
  221. 14: *FillT <start> <end>|+<length> <string>
  222. 15: *FillW <start> <end>|+<length> <words list>
  223. 16: *FindB <start> <binary number> [Q|N|E|F]
  224. 17: *FindC <start> <word|%binary|mnemonic string>
  225. 18: *FindH <start> <Hex list> [Q|N|E|F]
  226. 19: *FindM <start> <Mnemonic string> [Q|N|E|F]
  227. 20: *FindN <start> <32-bit number> [Q|N|E|F]
  228. 21: *FindT <start> <string> [[C] [Q|N|E|F]]
  229. 22: *FindW <start> <word> [Q|N|E|F]
  230. 23: *Fjoin <1st file> <2nd file> [<target file>]
  231. 24: *FMcompare <filename> <addrs> [<max diff>]
  232. 25: *Freplace <srs filename> <srs string> <trgt filename> <trgt string> [C]
  233. 26: *Heap [<address>]
  234. 27: *Index 
  235. 28: *Labels 
  236. 29: *LoadLabels <filename>
  237. 30: *Mcommands [<relocatable module name>]
  238. 31: *Mcompare <start> <end>|+<length> <with> [<max diff>]
  239. 32: *Mdump <f/rmat> <start> [<end>|+<length> [<offset>]]
  240. 33: *Medit [[<address>] [<format>]] | [<label>]
  241. 34: *Mmap 
  242. 35: *Move <start> <end>|+<length> <to>
  243. 36: *MPage [<page number>]
  244. 37: *Reverse <start> <end>|+<length>
  245. 38: *SaveArc <filename>
  246. 39: *SaveLabels <filename>
  247. 40: *Slow [<value>]
  248. 41: *Swap <start> <end>|+<length> <with>
  249. 42: *SwiC [<SWI chunck>]
  250. 43: *SwiM <relocatable module name>
  251. 44: *SwiN <SWI name>
  252. 45: *SwiS <SWI number>
  253. 46: *System
  254. 47: *Timing <start> [<end>|+<length> [<offset>]]
  255. 48: *Tools [G|D|M]
  256. 49: *Vector [<vector number>]
  257. 50: *Where <address>
  258.  
  259.  
  260.               *****************************************
  261.               *       Disc and file commands          *
  262.               *****************************************
  263.  
  264.  
  265.  General Notes:
  266.  
  267.   -   Where <drive number> is given, this identifies the drive number
  268.       as 0 to 7 or A to H, not a disc name.
  269.   -   <format> means the editor format (B,H,W,T,M,N or Y) not the disc
  270.       format.
  271.   -   The *Dput and *Dget commands allow unrestricted length of data
  272.       to be specified, they are not limited to a sector aligned lengths
  273.       or addresses.   
  274.   -   All disc and memory addresses are assumed to be hexadecimal values
  275.       unless the address is proceeded with base number.
  276.   -   It is best to use the commands menu built into the memory and disc
  277.       editors to perform the equivalent *Dget and *Dput operations. This
  278.       makes it easier and safer because you can see where data is copied
  279.       from or copied to.
  280.   
  281.   WARNING: You should know what you are doing when using any of the
  282.            disc commands.
  283.  
  284.     =======================================================================
  285.  1: *Dedit <drive number> [<address>] [<format>]
  286.     =======================================================================
  287.  
  288.     Enters any one of the 7 disc editors at the given address.
  289.     If no address or format is given then the last visited address
  290.     will be seeked and the last remembered disc editor is entered.
  291.     The drive number must be given. This must be a drive number, not
  292.     a disc name.
  293.     The disc editors can edit any disc recognized by the Operating
  294.     System including all ADFS formats, RAM disc, DOS and ATARI discs.
  295.     As well as custom known disc formats. See the section on the
  296.     Disc Editor.
  297.  
  298.     Parameters:
  299.     ===========
  300.  
  301.     <Drive number>    can be any of the values 0 to 7 or A to H.
  302.  
  303.     <address>         optional disc address.
  304.  
  305.     <format>          optional editor format.
  306.  
  307.  
  308.     Examples:
  309.     =========
  310.  
  311.              *Dedit  0  0  T      Enter the disc Text editor at
  312.                                   address 0 reading from drive 0.
  313.  
  314.              *Dedit  4  H         Enter the disc Hex editor at the
  315.                                   last visited disc address on drive
  316.                                   number 4 (Hard Disc 1).
  317.  
  318.     Possible errors: Bad drive
  319.     ================ Bad number
  320.                      Unknown ARCTOOLS editor
  321.  
  322.     Related commands: *Dput, *Dget.
  323.     =================
  324.  
  325.  
  326.  
  327.     =======================================================================
  328.  2: *Dget <drive number> <disc adrs> <end>|+<length> <memory adrs>
  329.     =======================================================================
  330.  
  331.     Purpose: Copy a block of data from disc to memory.
  332.     ========
  333.  
  334.     *DGET CAN GET DATA FROM ANY ADDRESS AND OF ANY LENGTH.
  335.  
  336.     Note: The memory area that the disc data will be copied to must
  337.           lie in logical Ram.
  338.  
  339.     Parameters:
  340.     ===========
  341.  
  342.     <drive>             :drive number 0-7 or A-H
  343.     <disc adrs>         :start address of data on disc
  344.     <end>|+<length>     :marker of data on disc. This can be given
  345.                          as the end address or the length of data.
  346.     <memory adrs>       :start address of memory to copy data to.
  347.  
  348.     Examples:
  349.     =========
  350.  
  351.     *Dget 0 0 +400 60000        Copy 1024 bytes starting at disc address
  352.                                 0 to memory starting at 60000
  353.  
  354.     *Dget 0 1A +10 60005        Copy 10 bytes starting at disc address
  355.                                 1A to memory starting at 60005.
  356.                                 This actually copies the disc name to RAM!
  357.  
  358.     Possible error: Bad drive
  359.     =============== Bad memory
  360.                     Non writable memory
  361.  
  362.     Related commands: *Dput, *Dedit.
  363.     ================
  364.  
  365.     =======================================================================
  366.  3: *Dlock [<ON|OFF>]
  367.     =======================================================================
  368.  
  369.     Purpose: To software write-protect ALL drives.
  370.     ========
  371.  
  372.     Examples:
  373.     =========
  374.     *Dlock         Reports the status of the Dlock command, This
  375.                    will show either:
  376.                    'All drives are write-enabled', or
  377.                    'All drives are write-protected'.
  378.  
  379.     *Dlock ON      Write protects all drives.
  380.  
  381.     *Dlock OFF     Removes the *Dlock protection.
  382.  
  383.     When Dlock is ON, an attempt to write to a drive will produce the
  384.     error message: 'Protected drive'
  385.  
  386.  
  387.     Possible errors: Bad parameter
  388.     ================
  389.  
  390.     Related commands:  None.
  391.     =================
  392.  
  393.  
  394.     =======================================================================
  395.  4: *Dmap [<drive>]
  396.     =======================================================================
  397.  
  398.     Purpose: Display the free disc space map.
  399.     ======== This command provides a neat way of display the free
  400.              space map on disc by intercepting the OS *MAP command.
  401.  
  402.     This command shows the map number, its start address and its size
  403.     together with the total free space map on the specified disc.
  404.  
  405.     Example:  *Dmap 4     Displays the free space map on the Hard disc.
  406.     =======
  407.  
  408.     Possible errors: Bad drive
  409.     ================
  410.  
  411.     Related commands: None.
  412.     ================
  413.  
  414.     =======================================================================
  415.  5: *Dput <drive> <memory adrs> <end>|+<length> <disc adrs>
  416.     =======================================================================
  417.  
  418.     Purpose: Copy data from memory to disc directly.
  419.     ========
  420.  
  421.     *DPUT CAN COPY DATA TO ANY ADDRESS AND ANY LENGTH OF DISC.
  422.  
  423.     The memory block must lie in a logical Ram area.
  424.  
  425.     Parameters:
  426.     ===========
  427.  
  428.     <drive>             :drive number 0-7 or A-H
  429.     <memory adrs>       :start adrs of data in memory
  430.     <end>|+<length>     :marker of memory data. This can be given
  431.                          as an end address or data length.
  432.     <disc adrs>         :start address on disc to copy data to.
  433.  
  434.     Examples:
  435.     =========
  436.  
  437.     *Dput 0 8F00 900 2800       Copies 256 bytes from memory address
  438.                                 8F00 to disc starting at address 2800.
  439.  
  440.     *Dput 0 60000 +10 1A        Copies 10 bytes starting at memory
  441.                                 address 60000 to disc starting at
  442.                                 address 1A
  443.  
  444.     Possible Errors: Bad drive
  445.     ================ Bad memory
  446.  
  447.     Related commands: *Dget, *Dedit.
  448.     =================
  449.  
  450.  
  451.     =======================================================================
  452.  6: *Fcompare <first file> <second file> [<max difference>]
  453.     =======================================================================
  454.  
  455.     Purpose: Perform byte comparison of two files.
  456.     ========
  457.  
  458.     This command compares two files byte for byte.
  459.     If the <max difference> is ommited, the comparison will stop
  460.     after 10 differences.
  461.     To display all difference: give a max difference value of 0.
  462.     Any difference will be shown as:
  463.  
  464.     Different at <address>: 1st file = <Byte> / 2nd file = <Byte>
  465.  
  466.     The 'different at address' is the offset within the files.
  467.  
  468.     If the two files compare okay, then the message "Comparion OK"
  469.     will be shown.
  470.  
  471.     MOTE: This command performs a byte for byte comparison. It does
  472.           not check to see if the two files have identical lengths.
  473.           The comparison stops when either file end is reached.
  474.  
  475.     Examples:
  476.     =========
  477.  
  478.     *Fcompare Document  Manual 0    Lists all differences between
  479.                                        the two files.
  480.  
  481.     *Fcompare File1 File2   5       Compare 'File1' with 'File2', stopping
  482.                                     after 5 differences.
  483.  
  484.  
  485.     Possible errors: File not found.
  486.     ================
  487.  
  488.     Related commands:  *FMcompare, *Mcompare.
  489.     ================= 
  490.  
  491.     =======================================================================
  492.  7: *Fcount <filename> <string> [C]
  493.     =======================================================================
  494.  
  495.     Purpose: Counts the number of occurences of a string in the given
  496.     ======== filename.
  497.              String containing a number of spaces must be enclosed in
  498.              quotes.
  499.              The number of occurences is echoed on the screen dynamically.
  500.  
  501.     Parameters:
  502.     ===========
  503.  
  504.     <filename>       The name of file to search in.
  505.     <string>         The string to count.
  506.     [C]              Optional switch which when included allows the
  507.                      counting of strings to be case insensitive.
  508.  
  509.     Examples:
  510.     =========
  511.  
  512.     *Fcount TextFile  "The"        Counts the number of occurences of the
  513.                                    string 'The' in the file 'TextFile'
  514.  
  515.     *Fcount MyFile |M              Counts the number of occurences of the
  516.                                    string |M (i.e. character ASCII code 13)
  517.                                    in the file 'MyFile'
  518.  
  519.     *Fcount Prog ". This is" C     Counts the number of occurrences of the
  520.                                    string '. This is' in the file 'Prog'.
  521.                                    The search is case insensitive.
  522.  
  523.     The message 'No match found' will be reported if command can not find
  524.     the requested string.
  525.  
  526.     Related errors: Bad parameter
  527.     ===============
  528.  
  529.     Related commands: *Freplace
  530.     =================
  531.  
  532.  
  533.     =======================================================================  
  534.  8: *Fdump <filename> <format> [<offset>]
  535.     =======================================================================
  536.  
  537.     Purpose: Dump a file to screen using any of the 7 dump formats.
  538.     ========
  539.  
  540.     This command allows a file stored on disc to be dummped into the
  541.     screen, or printer if VDU 2 or CTRL+B has been issued.
  542.     Using the optional <offset> address you can dump a file as though
  543.     it was stored in a particular address. In the Mnemonics dump
  544.     format, any reference to offset addresses in instructions will
  545.     be taken care of.
  546.  
  547.     Parameters:
  548.     ===========
  549.  
  550.     <filename>             A valid filename.
  551.     <format>               Editor format: B, H, M, N, T, W or Y.
  552.     <offset>               Optional offset address to be used in place
  553.                            of the zero offset address.
  554.  
  555.     Examples:
  556.     =========
  557.  
  558.     *Fdump myfile M 3800000   Dump 'myfile' using the dis-assembler
  559.                               showing addresses as though the file was
  560.                               in the system ROM address space.
  561.  
  562.     *Fdump Doc T              Dump the file 'Doc' using the Text dump
  563.                               format.
  564.     
  565.  
  566.     Possible errors: Unknown ARCTOOLS editor
  567.     ================ Bad number
  568.  
  569.     Related commands: *Mdump
  570.     =================
  571.  
  572.     =======================================================================
  573.  9: *Files
  574.     =======================================================================
  575.  
  576.     Purpose: List details of all currently open files.
  577.     ========
  578.  
  579.     The command takes no parameters and prints out the following
  580.     information on each currently open file:
  581.  
  582.     1. The handle number. The OS assigns a handle number for each
  583.        file at time of opening which programs use to access the
  584.        data in the file or to write data to the file.
  585.     2. The read/write status. The read/read status indicates the type
  586.        of access method used when the file was opened as follows:
  587.        a) Read Only :  OPENIN used.
  588.        b) Read/Write:  OPENOUT or OPENUP used.
  589.     3. The file extent. This is the size of the file.
  590.     4. The current pointer position in the file. The pointer position
  591.        is controlled by the OS or by the user and is used as a mark
  592.        to indicate where the data is read from or written to in the
  593.        file.
  594.  
  595.     If there are no open files. The message 'No open files' is displayed.
  596.  
  597.  
  598.     Possible errors: None.
  599.     ===============
  600.  
  601.     Related commands: None.
  602.     ================
  603.  
  604.     =======================================================================
  605. 10: *Fjoin <first file> <second file> [<target file>]
  606.     =======================================================================
  607.  
  608.     Purspoe: To join two files.
  609.     ========
  610.  
  611.     This command may be used to append one file to another, or
  612.     make a new file out of two different files by appending
  613.     them two each other.
  614.     Note: Different filenames should be given to the three files.
  615.  
  616.     Parameters:
  617.     ===========
  618.  
  619.     <first file>            Name of the first file.
  620.     <second file>           Name of the second file.
  621.     <target file>           Optional target file.
  622.  
  623.  
  624.     Examples:
  625.     =========
  626.  
  627.     *Fjoin Doc1 Doc2  New     Makes a new file called 'New' out of
  628.                               the two files; 'Doc1' and 'Doc2'.
  629.                               The new file will be stamped with the
  630.                               file type 'Data'.
  631.  
  632.     *Fjoin File1 File2        Appends File2 to File1. In this case File1
  633.                               will have File2 added to it. File1 will
  634.                               maintain its old File Type.
  635.  
  636.  
  637.     Possible errors: File open
  638.     ================
  639.  
  640.     Related commands: None.
  641.     =================
  642.  
  643.  
  644.     =======================================================================
  645. 11: *FMcompare <filename> <address> [<max difference>]
  646.     =======================================================================
  647.  
  648.     Purpose: Compares the content of a file with that of the given
  649.     ======== memory area.
  650.  
  651.     This command compares a file with the content of memory.
  652.     If the <max difference> is ommited, the comparison will stop
  653.     after 10 differences.
  654.     To display all difference: give a max difference value of 0.
  655.     Any difference will be shown as:
  656.  
  657.     Different at <address>: file = <Byte> / memory = <Byte>
  658.  
  659.     The 'different at address' is the offset within the file, not
  660.     the memory address, and always starts at zero. Bytes values
  661.     are shown in hexadecimal.
  662.  
  663.     Parameters:
  664.     ===========
  665.  
  666.     <filename>                 Valid filename.
  667.     <address>                  Start of memory to compare with.
  668.     <maximum difference>       Optional max difference allowed.
  669.  
  670.     Examples:
  671.     =========
  672.  
  673.     *FMcompare MyProg  8f00      Compares the content of the file
  674.                                  'MyProg' with the content of memory
  675.                                  starting at address &8F00.
  676.  
  677.     *FMcompare Text 8F00 0       Compare the content of file 'Text'
  678.                                  with memory starting at &8F00, listing
  679.                                  all differences.
  680.  
  681.  
  682.     Possible errors: Bad number
  683.     ================ Bad memory
  684.                      None logical ram address
  685.  
  686.  
  687.     Related commands: *Fcompare, *Mcompare.
  688.     =================
  689.  
  690.     =======================================================================
  691. 12: *Freplace <srs filename> <srs string> <trgt filename> <trgt string> [C]
  692.     =======================================================================
  693.  
  694.     Purpose: To replace or delete a string in a file.
  695.     ========
  696.  
  697.     This command replaces the given <srs string> with the given
  698.     <trgt string>. Any reference to the <srs string> in the <srs filename>
  699.     is replaced by the <trgt string> and placed in the new file
  700.     <trgt filename>.
  701.     If the <srs string> is to be deleted, then the use '-d' for the
  702.     <trgt string>.
  703.     When the 'C' switch is included, the search for the string becomes
  704.     case insensitive.
  705.  
  706.     Parameters:
  707.     ===========
  708.  
  709.     <srs filename>     Filename to search for string inside.
  710.     <srs string>       String to search for in the <srs filename>.
  711.     <trgt filename>    New file to be created.
  712.     <trgt string>      String which will replace the <srs string>.
  713.     [C]                When included the search becomes case insensitive.
  714.  
  715.     Examples:
  716.     =========
  717.  
  718.     *Freplace Documnt1 "Roger" Documnt2 "Mike"
  719.                            Replaces all references to the string 'Roger'
  720.                            in the file Documnt1 by the string "Mike", and
  721.                            places the result in Cocumnt2.
  722.  
  723.     *Freplace ReadMe |M  ReadMe2  |M|J
  724.                            Replaces all references to <CR> in the file
  725.                            'ReadMe' by the ASCII code <CR><LF>, creating
  726.                            a new file called 'ReadMe2'.
  727.                            This example shows how a text file under RISC
  728.                            OS system can be converted to a file readable
  729.                            under MS DOS.
  730.  
  731.     *Freplace MyProg |J  NewFile -d
  732.                            Creates a file called 'NewFile' identical to
  733.                            file 'MyProg' but removing any ASCII codes 12
  734.                            (Line feed).
  735.  
  736.     Possible errors: File not found
  737.     ================ Bad parameter
  738.  
  739.     Related commands: *Fcount
  740.     =================
  741.  
  742.  
  743.  
  744.  
  745.                   +++++++++++++++++++++++++++++++++
  746.                   +       Memory Commands         +
  747.                   +++++++++++++++++++++++++++++++++
  748.  
  749.     General Notes:
  750.     ==============
  751.  
  752.     - Extreme caution should be exercised when using the memory commands
  753.       as most of them have a destructive effect on data in memory.
  754.  
  755.     - To be able to write into an area of memory, the memory block must
  756.       exist in logical or physical Ram. No write operation is allowed
  757.       into the the ROM address space (above &3400000).
  758.  
  759.     - The memory commands have been optimized for speed and efficiency.
  760.  
  761.  
  762.  
  763.  
  764.     =======================================================================
  765.  1: *Clear <start> <end>|+<length>
  766.     =======================================================================
  767.  
  768.     Purpose: Wipe clean a block of memory.
  769.     ========
  770.  
  771.     Parameters:
  772.     ===========
  773.  
  774.     <start>               The start address of memory area
  775.     <end>                 The end address of memory area
  776.     +<length>             The length of memory area
  777.  
  778.     Examples:
  779.     =========
  780.  
  781.     *Clear 9000 +100      Clears 256 bytes starting at address &9000
  782.     *Clear 9000 9100      same as above command
  783.  
  784.     Note: The memory area to be cleared must be writable.
  785.           If the end address of the area to be cleared lies in
  786.           a memory area different than that of the start address,
  787.           ARCTOOLS will clear up to the end of the current memory
  788.           area.
  789.  
  790.     Possible errors:
  791.     ================
  792.  
  793.     Related commands: *FillH, *FillT, *FillW.
  794.     =================
  795.  
  796.  
  797.     =======================================================================
  798.  2: *FillH <start> <end>|+<length> <hex list>
  799.     =======================================================================
  800.  
  801.     Purpose:  Fill memory area with a sequence of bytes.
  802.     ========
  803.  
  804.     This command allows a region of memory to be filled with
  805.     specified data.
  806.     The given sequence of bytes is repeatedly written to bytes in the
  807.     given memory area until the entire block has been filled.
  808.  
  809.     Parameters:
  810.     ===========
  811.  
  812.     <start>           Start address of the memory block.
  813.     <end>             End address of the memory block.
  814.     +<length>         Length of the memory block.
  815.     <hex list>        List of space separated hexadecimal bytes
  816.                       to fill the requested memory area with.
  817.  
  818.     Examples:
  819.     =========
  820.  
  821.     *FillH 10000 +200 FF          Fills &200 bytes of memory area starting
  822.                                   at address &10000 with the hex byte &FF.
  823.  
  824.     *FillH 20000 +100 "0 0 1 1"   Fill &100 bytes of memory area starting
  825.                                   at address &20000 with the bytes
  826.                                   0 0 1 1. 
  827.  
  828.  
  829.     Possible errors:  None logical ram address
  830.     ================  Non-writable memory
  831.                       Bad memory
  832.                       Bad number
  833.  
  834.     Related commands: *FillT, *FillW
  835.     =================
  836.  
  837.     =======================================================================
  838.  3: *FillT <start> <end>|+<length> <string>
  839.     =======================================================================
  840.  
  841.     Purpose: Fill memory area with a string.
  842.     ========
  843.  
  844.     The given string is repeatedly written to bytes in the given
  845.     memory range until the entire block has been filled.
  846.  
  847.     Parameters:
  848.     ===========
  849.  
  850.     <start>           Start address of the memory block.
  851.     <end>             End address of the memory block.
  852.     +<length>         Length of the memory block.    
  853.     <string>          String to fill memory with. The Operating System
  854.                       GSTranslate convention for specifying control
  855.                       characters may be used within the string.
  856.  
  857.     Examples:
  858.     =========
  859.  
  860.     *FillT  45000 +1000 "Risc"   This would fill the memory range &45000
  861.                                  to &46000 with the string "Risc"
  862.  
  863.     *FillT  45000 46000 "Risc"   Similar to the above.
  864.  
  865.     *FillT  20000 +100 "|M"      Fill the memory area with the ASCII code
  866.                                  given by CTRL+M, i.e. character with
  867.                                  ASCII code 13.
  868.  
  869.  
  870.     Possible errors:  None logical ram address
  871.     ================  Non-writable memory
  872.                       Bad memory
  873.  
  874.     Related commands: *FillH, *FillW
  875.     =================
  876.  
  877.  
  878.     =======================================================================
  879.  4: *FillW <start> <end>|+<length> <words list>
  880.     =======================================================================
  881.  
  882.     Purpose: Fill memory area with 32-bit numbers.
  883.     ========
  884.  
  885.     The memory block must be word aligned.
  886.  
  887.     Parameters:
  888.     ===========
  889.  
  890.     <start>           Start address of the memory block.
  891.     <end>             End address of the memory block.
  892.     +<length>         Length of the memory block.
  893.     <word list>       List of 32-bit numbers space separated.
  894.  
  895.     Examples:
  896.     =========
  897.  
  898.     *FillW 19000 21000 "10203040 1234 1 2"
  899.  
  900.                        Fill memory area &19000 to &21000 with the 32-bit
  901.                        numbers:
  902.                        10203040, 00001234, 00000001, 00000002
  903.  
  904.     *FillW 21400 +200 "1 2 3 4"
  905.  
  906.                        Fill memory area &21400 to &21600 with the 32-bit
  907.                        numbers:
  908.                        00000001, 00000002, 00000003, 00000004
  909.  
  910.  
  911.  
  912.     Possible errors:  None logical ram address
  913.     ================  Non-writable memory
  914.                       Bad memory
  915.                       Non aligned address
  916.                       Bad number
  917.  
  918.     Related commands: *FillH, *FillT
  919.     =================
  920.  
  921.  
  922.  
  923.               ===========================================
  924.               General notes on the memory search commands
  925.               ===========================================
  926.  
  927.    The memory search commands are: *FindB, *FindC, *FindH, *Find, *FindM
  928.    *FindN and *FindT.
  929.  
  930.    These commands search all memory starting at the given address for
  931.    the given data.
  932.    All of the search commands except *FindC, have optional switches
  933.    which are Q, N, E or F. The meaning of each switch is:
  934.    Q : Quit after first match.
  935.    N : Go for Next match. This gives a list of all matching addresses.
  936.    E : Enter the appropriate editor at the first match.
  937.    F : Full search. This is a count option which will give the number
  938.        of matches found.
  939.    If no Q, N, E or F switch is given then, the message:
  940.    "Found at address &xxxxxxxx (Quit/Next/Edit) (Q/N/E)?" will
  941.    be shown. Press Q to quit, N for next match or E to enter the
  942.    memory editor at the shown address. At any time pressing Escape
  943.    key stops the search. Once in the memory editors, use the key
  944.    combination CTRL+Back Space to search for the next match. The
  945.    Back Space key is the key to the right of the Pound key. You can switch
  946.    to another editor and continue the search.
  947.  
  948.    At any time, the Escape key can be used to abandon the search.
  949.  
  950.  
  951.    NOTE: It is possible that the search commands will report matches
  952.          found in memory locations, that upon entering the editors,
  953.          the contents of these locations have changed.
  954.          The search routines will report that a 32-bit number or a
  955.          mnemonic string is found at say &1C00010, but the content of
  956.          that location is different!!!. The reason behind this is that
  957.          this area (starting at &1C00000) is used as the OS heap and
  958.          Supervisor stack were registers are stored when pushed on the
  959.          stack. The same applies to area starting at &1F00000 which is
  960.          used for the cursor, OS space and the sound DMA.
  961.          ARCTOOLS stores the numbers to search for in registers
  962.          which are pushed into the stack when sub-routines are called.
  963.          The search routine will find the register content pushed into
  964.          the stack, but as soon as the search routine exits to report to
  965.          you that a match is found, the registers would have been pulled
  966.          out of the stack and the stack has been replaced by other values.
  967.          This is the reason behind this strange behaviour. This is considered
  968.          normal and is not a bug.
  969.  
  970.  
  971.     =======================================================================
  972.  5: *FindB <start> <binary number> [<Q|N|E|F>]
  973.     =======================================================================
  974.  
  975.     Purpose: Memory search for a binary number.
  976.     ========
  977.  
  978.     This command is used to search all the machine memory starting
  979.     at the given address for a binary number.
  980.     Characters allowed in the binary number are 0, 1 and #. The
  981.     entered number is considered a 32-bit binary number.
  982.     If the entered binary number is 11, then this will translate into:
  983.     00000000000000000000000000000011
  984.  
  985.     The command will list all memory addresses that have the same
  986.     number.
  987.  
  988.     Parameters:
  989.     ===========
  990.  
  991.     <start>                 Memory start address.
  992.     <binary number>         A binary number. Single wildcards
  993.                             allowed.
  994.     <Q>                     Quit after first found match.
  995.     <N>                     Show Next address. This causes all
  996.                             all matching memory addresses to be
  997.                             listed into the screen.
  998.     <E>                     Enter the editor at first match address.
  999.     <F>                     Full. This performs a count of the
  1000.                             number of matches found.
  1001.  
  1002.     Examples:
  1003.     =========
  1004.  
  1005.     *FindB  0   11          Lists all addresses that contain the binary
  1006.                             number %11.
  1007.  
  1008.     *FindB  0  ####1111000000000000000000000000  F
  1009.                             Count all matches of the given binary number.
  1010.                             This actually counts all SWI instructions
  1011.                             in the machine.
  1012.  
  1013.  
  1014.     Possible errors: Bad memory
  1015.     ================ Bad parameter
  1016.                      Bad number
  1017.  
  1018.     Related commands: *FinH, *FindM, *FindT, *FindC, *FindN, *FindW
  1019.     =================
  1020.  
  1021.  
  1022.     =======================================================================
  1023.  6: *FindC <start> <word|%binary|Mnemonic string>
  1024.     =======================================================================
  1025.  
  1026.     Purpose: Provide a mnemonic screen dump of all occurrences of
  1027.     ======== the given match code.
  1028.  
  1029.     This command will dump to the screen in the current dis-assembler
  1030.     display format all occurrences of the given code.
  1031.     The code to search for can be given as a 32-bit number (Word),
  1032.     a 32-bit binary number or as a mnemonic string.
  1033.     If the code is enclosed in quotes then it is assumed to be a
  1034.     mnemonic string, if it is proceeded by the % sign then it is
  1035.     assumed to be a binary number, otherwise it is a 32-bit hex
  1036.     number.
  1037.     Single wildcards are only allowed in the word or binary number
  1038.     code.
  1039.  
  1040.     Parameters:
  1041.     ===========
  1042.  
  1043.     <word>                   A 32-bit hex number. Single wild cards
  1044.                              allowed
  1045.     <%cinary>                A 32-bit binary number, proceeded by the
  1046.                              % sign. Single wildcards allowed.
  1047.     <Mnemonic string>        A string of assembly code.
  1048.  
  1049.     Examples:
  1050.     =========
  1051.  
  1052.     *FindC 3800000 "SWI OS_WriteS"    Dump to screen all references to the
  1053.                                       SWI OS_Find instruction starting at
  1054.                                       address &3800000 (System ROM area).
  1055.  
  1056.     *FindC 1800000 #F######      Dump to screen all reference of SWI
  1057.                                  instructions starting at address &1800000.
  1058.  
  1059.     *FindC 0 %####00010###########00001001###
  1060.                                  Dump to screen all references to the
  1061.                                  ARM3 SWP instruction.
  1062.  
  1063.     *FindC 3800000 %####1110000#########111100010000
  1064.                                  Dump to screen all reference to the
  1065.                                  ARM3 cache control register operations in
  1066.                                  the system ROM.
  1067.  
  1068.  
  1069.     Possible errors: Bad memory
  1070.     ================ Bad parameter
  1071.                      Bad number
  1072.  
  1073.     Related commands: *FinH, *FindM, *FindT, *FindW, *FindN, *FindB
  1074.     =================
  1075.  
  1076.  
  1077.     =======================================================================
  1078.  7: *FindH <start> <hex list> [<Q|N|E|F>]
  1079.     =======================================================================
  1080.  
  1081.     Purpose: Search memory for a list of hex bytes.
  1082.     ========
  1083.  
  1084.     Parameters:
  1085.     ===========
  1086.  
  1087.     <start>                 Memory start address
  1088.     <hex list>              A list of hexadecimal byte numbers
  1089.                             Single wildcards allowed.
  1090.     <Q>                     Quit after first found match.
  1091.     <N>                     Show Next address. This causes all
  1092.                             all matching memory addresses to be
  1093.                             listed into the screen.
  1094.     <E>                     Enter the editor at first match address.
  1095.     <F>                     Full. This performs a count of the
  1096.                             number of matches found.
  1097.  
  1098.     Examples:
  1099.     =========
  1100.  
  1101.     *FindH &8F00 "0D FF"    Search memory for the bytes &0D followed by
  1102.                             by &FF starting at address &8F00. This finds
  1103.                             the end address of a BASIC program in
  1104.                             memory.
  1105.  
  1106.     *FindH 0 "FF ## FF 00"  Search for the bytes sequence which has the
  1107.                             first byte &FF, third byte &FF, fourth byte
  1108.                             &00, don't care about second byte.
  1109.  
  1110.     *FindH 3800000 "1#F"    Similar to search for "1# 0F", starting at
  1111.                             address &3800000.
  1112.  
  1113.     *FindH 0 "#A 20 F# ## 34"  Search for the bytes sequence with the
  1114.                                following criteria:
  1115.                                1st byte: low nibble = &A
  1116.                                2nd byte: &20
  1117.                                3rd byte: high nibble = &F
  1118.                                4th byte: don't care
  1119.                                5th byte: &34
  1120.  
  1121.     Possible errors: Bad memory
  1122.     ================ Bad parameter
  1123.                      Bad number
  1124.  
  1125.     Related commands: *FinB, *FindM, *FindT, *FindC, *FindN, *FindW
  1126.     =================
  1127.  
  1128.     =======================================================================
  1129.  8: *FindM <start> <Mnemonic string> [<Q|N|E|F>]
  1130.     =======================================================================
  1131.  
  1132.     Purpose: Search memory starting at the given address for
  1133.     ======== mnemonics.
  1134.  
  1135.     This command allows the search of a line of assembly code
  1136.     to be performed. The mnemonic must be enclosed in quotes.
  1137.     Any string which ARCTOOLS can assemble can be searched for.
  1138.     The current version of ARCTOOLS does not allow wildcards in
  1139.     the given mnemonic string.
  1140.  
  1141.     Parameters:
  1142.     ===========
  1143.  
  1144.     <Start>                 Memory start address.
  1145.     <Mnemonic string>       Valid mnemonic string.
  1146.     <Q>                     Quit after first found match.
  1147.     <N>                     Show Next address. This causes all
  1148.                             all matching memory addresses to be
  1149.                             listed into the screen.
  1150.     <E>                     Enter the editor at first match address.
  1151.     <F>                     Full. This performs a count of the
  1152.                             number of matches found.
  1153.     
  1154.     Examples:
  1155.     =========
  1156.  
  1157.     *FindM   0  "STMFD R13!,{R14}"    Search memory starting at address
  1158.                                       &0000 for the mnemonic string
  1159.                                       "STMFD R13!,{R14}"
  1160.                                      
  1161.     *FindM 3800000 "SWI OS_ReadC"     Searches the ROM for the all
  1162.                                       occurrences of SWI "OS_ReadC".
  1163.  
  1164.     *FindM 3800000 "SWI OS_ReadC" F   Counts the number of occurrences
  1165.                                       of the SWI "OS_ReadC"
  1166.  
  1167.     *FindM 3800000 "LDRB R0,[R1]" E   Search for the given assembly
  1168.                                       code in the system ROM, entering
  1169.                                       the Mnemonics editor at the first
  1170.                                       Match found. Use CTRL+Back Space
  1171.                                       for next match search.
  1172.  
  1173.     Possible errors: Bad memory
  1174.     ================ Bad parameter
  1175.  
  1176.     Related commands: *FinH, *FindB, *FindT, *FindC, *FindN
  1177.     =================
  1178.  
  1179.     =======================================================================
  1180.  9: *FindN <stirt> <32-bit number> [<Q|N|E|F>]
  1181.     =======================================================================
  1182.  
  1183.     Purpose: Search for a 32-bit number in memory.
  1184.     ========
  1185.  
  1186.     This command searches for a 32-bit decimal number. The sign
  1187.     can be given. Wildcards are not allowed.
  1188.  
  1189.     Parameters:
  1190.     ===========
  1191.  
  1192.     <start>                 Memory start address
  1193.     <32-bit number>         A 32-bit decimal number.
  1194.     <Q>                     Quit after first found match.
  1195.     <N>                     Show Next address. This causes all
  1196.                             all matching memory addresses to be
  1197.                             listed into the screen.
  1198.     <E>                     Enter the editor at first match address.
  1199.     <F>                     Full. This performs a count of the
  1200.                             number of matches found.
  1201.  
  1202.     Examples:
  1203.     =========
  1204.  
  1205.     *FindN  0  -1 N         List all occurrences of the decimal number
  1206.                             -1
  1207.  
  1208.     *FindN  3800000 -1 F    Count all occurrences of the number -1 in
  1209.                             the system ROM area.
  1210.  
  1211.     *FindN  3800000 123 E   Search for the number 123 in the system
  1212.                             ROM, entering the Numbers editor at the
  1213.                             first match found. Use CTRL+Back Space for
  1214.                             the next match.
  1215.  
  1216.  
  1217.     Possible errors: Bad memory
  1218.     ================ Bad parameter
  1219.                      Bad number
  1220.  
  1221.     Related commands: *FinH, *FindM, *FindT, *FindC, *FindB, *FindW
  1222.     =================
  1223.  
  1224.     =======================================================================
  1225. 10: *FindT <start> <string> [<Q|N|E|F>]
  1226.     =======================================================================
  1227.  
  1228.     Purpose: Search for a string in memory
  1229.     ========
  1230.  
  1231.     The operating system GSTranslate convention for specifying control
  1232.     characters may be used within the search string.
  1233.  
  1234.     Parameters:
  1235.     ===========
  1236.  
  1237.     <start>                 Memory start address
  1238.     <string>                A valid string which is GSTranslated.
  1239.                             Single wildcards allowed.
  1240.     <Q>                     Quit after first found match.
  1241.     <N>                     Show Next address. This causes all
  1242.                             all matching memory addresses to be
  1243.                             listed into the screen.
  1244.     <E>                     Enter the editor at first match address.
  1245.     <F>                     Full. This performs a count of the
  1246.                             number of matches found.
  1247.  
  1248.     Examples:
  1249.     =========
  1250.  
  1251.     *FindT 3800000 "Acorn"        Search the OS ROM for the string "Acorn".
  1252.  
  1253.     *FindT 3800000 "System" F     Count the number of occurrences of the
  1254.                                   string "System" in the OS ROM.
  1255.  
  1256.     *FindT 3800000 "System" C F   Similar to the above but the search is
  1257.                                   now case insensitive.
  1258.  
  1259.     *FindT 0 "|M|J" N             List all addresses that contain the
  1260.                                   control codes 13 followed by 10. These
  1261.                                   are the control codes for a carriage return
  1262.                                   and a line feed.
  1263.  
  1264.  
  1265.     Possible errors: Bad memory
  1266.     ================ Bad parameter
  1267.  
  1268.     Related commands: *FinH, *FindM, *FindW, *FindC, *FindN, *FindB
  1269.     =================    
  1270.  
  1271.  
  1272.     =======================================================================
  1273. 11: *FindW <start> <word> [<Q|N|E|F>]
  1274.     =======================================================================
  1275.  
  1276.     Purpose: Search memory for a given 32-bit hexadecimal number.
  1277.     ========
  1278.  
  1279.     Parameters:
  1280.     ===========
  1281.     
  1282.     <start>                 Memory start address
  1283.     <word>                  A 32-bit hexadecimal number. Single
  1284.                             wildcards allowed.
  1285.     <Q>                     Quit after first found match.
  1286.     <N>                     Show Next address. This causes all
  1287.                             all matching memory addresses to be
  1288.                             listed into the screen.
  1289.     <E>                     Enter the editor at first match address.
  1290.     <F>                     Full. This performs a count of the
  1291.                             number of matches found.
  1292.  
  1293.     Examples:
  1294.     =========
  1295.  
  1296.     *FindW  0 "######12"      Search memory starting at address &00000 for
  1297.                               the hex 32-bit number which has the LSB byte
  1298.                               of &12.
  1299.  
  1300.     *Find 1800000 "6A######"  Search memory starting at address &1800000 for
  1301.                               any 32-bit number with the msb byte equal to
  1302.                               &6A. This actually searches for all Branch
  1303.                               instructions with 'V' condition code set.
  1304.                               If you select to enter the editor, then you
  1305.                               are placed in the WORDs editors, however, you
  1306.                               can continue the search for the next match
  1307.                               from within any editor.
  1308.  
  1309.  
  1310.     Possible errors: Bad memory
  1311.     ================ Bad parameter
  1312.                      Bad number
  1313.  
  1314.     Related commands: *FinH, *FindM, *FindT, *FindC, *FindN, *FindB
  1315.     =================
  1316.  
  1317.     =======================================================================
  1318. 12: *Heap [<address>]
  1319.     =======================================================================
  1320.  
  1321.     Purpose: Examine the structure of a heap memory.
  1322.     ========
  1323.  
  1324.     Parameters:
  1325.     ===========
  1326.  
  1327.     [<address>]            Heap start address.
  1328.                            If no address is given the RMA area is examined.
  1329.  
  1330.     This command provides the following information:
  1331.  
  1332.     - Heap memory start address
  1333.     - Heap size
  1334.     - Total number of blocks
  1335.     - Total area used in the heap
  1336.     - Total free area in the heap
  1337.     - Largest free block
  1338.  
  1339.     The command also provides the following information on each block in
  1340.     the heap:
  1341.  
  1342.     - Block position
  1343.     - Start address in heap area
  1344.     - Size
  1345.     - Status (Claimed or free)
  1346.  
  1347.     If the Heap address is &1800000 (i.e. the RMA area), then this command
  1348.     provides more information on whether the heap block is a module code
  1349.     or a module buffer.
  1350.  
  1351.     Examples:
  1352.     =========
  1353.  
  1354.     *Heap          Displays the structure of the RMA heap
  1355.  
  1356.     *Heap 10000    Displays the structure of heap area starting at memory
  1357.                    address &10000
  1358.  
  1359.     Related error: 'Bad or corrupted heap'
  1360.     ==============
  1361.  
  1362.     Related commands: None.
  1363.     =================
  1364.  
  1365.  
  1366.  
  1367.     The block size shown is the one setup by the OS Heap Manager and not
  1368.     necessarily the one requested by the program. ie. the size includes
  1369.     the 4 bytes allocated at the start of each block which contains the
  1370.     block size. Additionally the Heap manager forces the block size to
  1371.     be a multiple of eight. Therefore, the minimum size of a block is 8
  1372.     bytes including the 4 bytes allocated to the size.
  1373.     Example: if a block size of 1022 was requested then the Heap Manager
  1374.              aligns the length to a word boundary becoming 1024 bytes, then
  1375.              adds 4 bytes to it making it 1028 bytes, then forces it to
  1376.              a multiple of eight making the length 1032 bytes.
  1377.     Using the above example it can be seen that although the user requested
  1378.     1022 bytes, the Heap Manager allocated 1032 bytes for the block.
  1379.     ARCTOOLS displays the Heap Manager's block size, not the user's requested
  1380.     size.
  1381.     Released blocks are highlighted by the word 'free'. The last block if any
  1382.     is the unused area in the heap.
  1383.     The *Heap command is very useful when developing programs that make use
  1384.     of the heap system as it is important for the program to release any
  1385.     memory area not being used and to be written in such a way as not to
  1386.     cause many holes to appear in the heap memory.
  1387.     RISC OS makes extensive use of a number of different heaps, the re-
  1388.     locatable module area (RMA) is used by the OS as one large heap. Other
  1389.     heap areas known to the author is the one starting at address &1C02000
  1390.     which is used to store system variables.
  1391.  
  1392.  
  1393.  
  1394.     =======================================================================
  1395. 13: *Mcompare <start> <end>|+<length> <with> [<max diff>]
  1396.     =======================================================================
  1397.  
  1398.     Purpose: Compares the content of two memory blocks byte for
  1399.     ======== byte.
  1400.  
  1401.     This command compares the content of two memory areas byte for
  1402.     for byte listing any differences on the screen.
  1403.     If the <max difference> is ommited, the comparison will stop
  1404.     after 10 differences.
  1405.     To display all difference: give a max difference value of 0.
  1406.     Any difference will be shown as:
  1407.  
  1408.     Different at <address> = <Byte> / <address> = <Byte>
  1409.  
  1410.     If the two memory blocks contain the same data, the message
  1411.     'Comparion OK' will be shown.
  1412.  
  1413.     Parameters:
  1414.     ===========
  1415.  
  1416.     <start>            Start address of the first memory block.
  1417.     <end>              End address of the first memory block.
  1418.     +<length>          Length of the first memory block.
  1419.     <with>             Start address of the second memory block.
  1420.     <max diff>         Optional maximum difference.
  1421.  
  1422.     Examples:
  1423.     =========
  1424.  
  1425.     *Mcompare 8F00 +1000 10000      Compare memory 8F00 to 9F00 with
  1426.                                     memory starting at 10000.
  1427.  
  1428.     *Mcompare 20000 +200 30000 0    Compare &200 bytes of memory starting
  1429.                                     at address &20000 with that starting
  1430.                                     at address &30000. List all possible
  1431.                                     differences.
  1432.  
  1433.  
  1434.     Possible errors:  None logical ram address
  1435.     ================  Non-writable memory
  1436.                       Bad memory
  1437.  
  1438.     Related commands: *FMcompare.
  1439.     =================
  1440.  
  1441.     =======================================================================
  1442. 14: *Mdump <format> <start> [<end>|+<length> [<offset>]]
  1443.     =======================================================================
  1444.  
  1445.     Purpose: Dump memory content in the specified dump format.
  1446.     ========
  1447.  
  1448.     When the memory is dumped into the screen, the memory addresses
  1449.     shown are those where the data comes from. However, using the
  1450.     <offset> address you can cause the result to show the dump of
  1451.     an area of memory as though it has come from another address.
  1452.     NOTE: To give the <offset> address, you should specify the <end> or
  1453.           +<length> parameter.
  1454.     If no <end> or +<length> parameter is given then a full screen dump
  1455.     is given. This depends on the current screen mode.
  1456.  
  1457.     Parameters:
  1458.     ===========
  1459.  
  1460.     <format>               Editor format: B, H, M, N, T, W or Y.
  1461.     <start>                Start address of the memory block.
  1462.     <end>                  Optional memory block end address.
  1463.     +<length>              Optional length of the memory block.
  1464.     <offset>               Optional offset address to be used in place
  1465.                            of the actual memory address.
  1466.  
  1467.     Examples:
  1468.     =========
  1469.  
  1470.     *Mdump M 3800000 +100 0    Dump &100 bytes starting at &3800000 using
  1471.                                the Mnemonic format. Show as though code
  1472.                                was at address &0000
  1473.  
  1474.     *Mdump T 8f00 20000        Dump memory area &8F00 to &20000 using the
  1475.                                Text format.
  1476.  
  1477.  
  1478.  
  1479.     Possible errors:  None logical ram address
  1480.     ================  Non-writable memory
  1481.                       Bad memory
  1482.                       Unknown editor format
  1483.  
  1484.     Related commands: *Fdump, *medit, *Dedit.
  1485.     =================
  1486.  
  1487.     =======================================================================
  1488. 15: *Medit [[<address> [<format>]] | [<label>]
  1489.     =======================================================================
  1490.  
  1491.     Purpose: Enter one of the 7 memory editors.
  1492.     ========
  1493.  
  1494.     This is the heart of ARCTOOLS commands. Any of the 7 memory
  1495.     editors can be accessed using this command.
  1496.     The address given is aligned to the next word-aligned address in
  1497.     the Mnemonic, Word, Numbers and Binary editors.
  1498.  
  1499.     Parameters:
  1500.     ===========
  1501.  
  1502.     *Medit                     Enter the last visited editor at the last
  1503.                                visited address.
  1504.     *Medit <address>           Enter the last visited editor at the given
  1505.                                memory address.
  1506.     *Medit <address> <format>  Enter the given editor at the given address.
  1507.     *medit <format>            Enter the given editor at the last visited
  1508.                                memory address.
  1509.     *medit <label>             Enter the Mnemonics editor at the given
  1510.                                label address.
  1511.  
  1512.     Examples:
  1513.     =========
  1514.  
  1515.     *medit 3800000 m           Enter the Mnemonics editor at the start of
  1516.                                system ROM space.
  1517.  
  1518.     *medit my_code             Enter the Mnemonics editor at the label
  1519.                                my_code. If the label is not defined, then
  1520.                                the error message 'Bad number' is given.
  1521.  
  1522.     *medit T                   Enter the text editor at the last visited
  1523.                                address.
  1524.  
  1525.  
  1526.     Possible errors: Bad number
  1527.     ================ Unknown editor format
  1528.  
  1529.     Related commands: *Mdump, *Fdump, *Dedit.
  1530.     =================
  1531.  
  1532.  
  1533.     =======================================================================
  1534. 16: *Mmap
  1535.     =======================================================================
  1536.  
  1537.     Purpose: Display the memory map of the machine.
  1538.     ========
  1539.  
  1540.     This command gives useful information on the logical memory
  1541.     mapping of the machine. The command shows the memory area
  1542.     name, its start address, its end address and its current
  1543.     size. The command also shows the total physical ram in the
  1544.     machine.
  1545.     The sizes of the IOC devices, the Low ROM and the High ROM areas
  1546.     are the maximum size available.
  1547.  
  1548.     On ARM 3 machines, the cache state of each memory area is displayed.
  1549.     Memory areas can be cacheable, uncacheable, cacheable and updateable,
  1550.     or cacheable and disruptive.
  1551.  
  1552.  
  1553.     Possible errors: None.
  1554.     ================
  1555.  
  1556.     Related commands: None.
  1557.     =================
  1558.  
  1559.  
  1560.     =======================================================================
  1561. 17: *Move <start> <end>|+<length> <to>
  1562.     =======================================================================
  1563.  
  1564.     Purpose: Copy a block of memory from one location to another.
  1565.     ========
  1566.  
  1567.     This command performs a copy of an area of memory to another
  1568.     location leaving the original area intact.
  1569.  
  1570.     Parameters:
  1571.     ===========
  1572.  
  1573.     <start>             Start address of memory to be copied.
  1574.     <end>               End address of the memory to be copied.
  1575.     +<length>           Length of the memory block to be copied.
  1576.     <to>                Target address.
  1577.  
  1578.     Examples:
  1579.     =========
  1580.  
  1581.     *Move  3800000 +2000  20000    Copies the first &2000 bytes from
  1582.                                    the memory area starting at address
  1583.                                    &3800000 to the area starting at
  1584.                                    address &20000.
  1585.  
  1586.     *Move 2004000  +1000 20000     Copies &1000 bytes from physical ram
  1587.                                    starting at &2004000 to address &20000.
  1588.  
  1589.  
  1590.  
  1591.     Possible errors:  None logical ram address
  1592.     ================  Non-writable memory
  1593.                       Bad memory
  1594.  
  1595.     Related commands: *Swap, *Reverse.
  1596.     =================
  1597.  
  1598.     =======================================================================
  1599. 18: *Mpage [<page number>]
  1600.     =======================================================================
  1601.  
  1602.     Purpose:  Displays the logical to physical memory mapping used by
  1603.     ========  the MEMC.
  1604.  
  1605.     Parameters:
  1606.     ===========
  1607.  
  1608.     [<page number>]         MEMC page number 0-255
  1609.                             If no page is given all pages are shown
  1610.  
  1611.     Information provided are:
  1612.  
  1613.     - Total pages in machines
  1614.     - Page size
  1615.     - Total mapped out pages (see below)
  1616.     - Page number, with its corresponding physical and logical memory
  1617.       addresses, its protection level number, its accessibility level and
  1618.       the memory area allocated to.
  1619.  
  1620.     The ARM can address 64 Mbytes of memory. This 64 Mbytes is divided
  1621.     into three areas. 16 Mbytes for physical RAM, 16 Mbytes for I/O and ROM,
  1622.     and 32 Mbytes for logical RAM. Address &0000000 to  &1FFFFFF is assigned
  1623.     to logical RAM and addresses &2000000 to &2FFFFFF are assigned to
  1624.     physical RAM. The I/O and ROM addresses start from &3000000 to &3FFFFFF.
  1625.     RISC OS uses the MEMC to map the 16 Mbytes of physical memory into
  1626.     16 Mbytes of logical memory. Using the current ARM-MEMC interface, the
  1627.     maximum RAM an ARM machine can support is 16 Mbytes.
  1628.     The mapping performed by the MEMC is achieved through a so called paging
  1629.     structure. The available physical memory is divided into pages. The
  1630.     max number of pages the current MEMC can support is 128. In a 1 Mbytes
  1631.     machine, each MEMC page is 8 Kbytes in size (1 Mbytes divided by 128).
  1632.     In a 4 Mbytes machines, the page size is 32 Kbytes. Each page has its
  1633.     own descriptor entry held in a so called CAM (Content-Addressable Memory)
  1634.     area in the MEMC. This MEMC structure allows fast logical to physical
  1635.     address translation without increase in memory access time.
  1636.     Each MEMC page can have its own protection level; 0, 1 or 2.
  1637.  
  1638.     The protection levels are defined as follows:
  1639.     Level 0 : The least privileged mode. This level allows read and
  1640.               write operation by everybody.
  1641.     Level 1 : This is read only in User mode. You must enter a Supervisor
  1642.               mode (SVC, IRQ or FIQ) to write into such page.
  1643.     Level 2 : This is not accessible in User Mode. You must switch into
  1644.               a Supervisor mode to read or write into such page.
  1645.  
  1646.     RISC OS provides two SWIs to enable reading and/or setting the MEMC
  1647.     memory map entry parameters together with protection levels.
  1648.     Using these SWIs, one can perform the following operation on memory
  1649.     pages:
  1650.            1. Un-map a page
  1651.            2. Map a page onto one page of logical memory
  1652.            3. Map a page onto several pages of logical memory
  1653.  
  1654.     The last operation (mapping one page into several pages of logical
  1655.     memory) is very unique in the sense that once several pages of
  1656.     logical Ram are mapped from one physical page, RISC OS will not
  1657.     be able to read or write from such pages. RISC OS can only read
  1658.     and write from pages that have a one-to-one mapping. The program
  1659.     that performed such map translation is the only one which could
  1660.     read and write those pages as it the one that has the old mapping
  1661.     parameters before being re-mapped.
  1662.     The Desktop uses this technique (one-to-many mapping) to hide
  1663.     pages of applications away when several applications are being
  1664.     multi-tasked and are sharing the same address (&8000).
  1665.     Such pages are referred to as mapped-out or hidden pages.
  1666.  
  1667.     In ARCTOOLS *Mpage command, mapped out pages are annotated 'Mapped out'
  1668.     and have the minimum accessibility. These pages are mapped to address
  1669.     &1F08000 which is part of the Cursor, OS space and Sound DMA area.
  1670.     All mapped out pages are mapped into this address, hence ARCTOOLS can not
  1671.     display the contents of such pages, however, if the machine contains
  1672.     mapped out pages, ARCTOOLS memory editors will allow display and editing
  1673.     of the memory page at address &1F08000 which will be one of the mapped
  1674.     out pages. Remember that ARCTOOLS memory editor allow editing of physical
  1675.     RAM and hence all pages of the machine are accessible.
  1676.     The mapping out technique is used extensively by the Desktop to hide
  1677.     programs and memory areas in a multi-tasking environment.
  1678.     Using *Mpage from within the Desktop will show all mapped out pages
  1679.     available.
  1680.     Memory pages may be hidden or mapped out by using the OS SWI call
  1681.     'OS_SetMemMapEntries' setting the page address to a value above
  1682.     32 Mbytes (&2000000).
  1683.  
  1684.  
  1685.     =======================================================================
  1686. 19: *Reverse <start> <end>|+<length>
  1687.     =======================================================================
  1688.  
  1689.     Purpose: Reverse the data in a block of memory.
  1690.     ========
  1691.  
  1692.     Parameters:
  1693.     ===========
  1694.  
  1695.     <start>             Start address of first memory block.
  1696.     <end>               End address of the first memory block
  1697.     +<length>           Length of the first memory block.
  1698.  
  1699.  
  1700.     Examples:
  1701.     =========
  1702.  
  1703.     *Reverse   8000 +100      Reverses 256 bytes of data starting
  1704.                               at memory address &8000
  1705.  
  1706.     *Reverse 10000 11000      Reverses the given memory block.
  1707.  
  1708.  
  1709.     Possible errors:  None logical ram address
  1710.     ================  Non-writable memory
  1711.                       Bad memory
  1712.  
  1713.     Related commands: *Swap, *Move.
  1714.     =================
  1715.  
  1716.  
  1717.     =======================================================================
  1718. 20: *Swap <start> <end>|+<length> <with>
  1719.     =======================================================================
  1720.  
  1721.     Purpose: Swaps to blocks of memory.
  1722.     ========
  1723.  
  1724.     Parameters:
  1725.     ===========
  1726.  
  1727.     <start>             Start address o& first memory block.
  1728.     <end>               End address of the first memory block
  1729.     +<length>           Length of the first memory block
  1730.     <with>              Start address of the second memory block
  1731.  
  1732.     Examples:
  1733.     =========
  1734.  
  1735.     *Swap  8000 +1000 9000    Swaps 4096 bytes (&1000) from the
  1736.                               memory area starting at &8000 with that
  1737.                               starting at &9000
  1738.  
  1739.     *Swap 8000 9000 9000      Similar to the above, using an end address
  1740.                               example of &9000.
  1741.  
  1742.     Possible errors:  Memory overlaps.
  1743.     ===============   None logical ram address
  1744.                       Non-writable memory
  1745.                       Bad memory
  1746.  
  1747.  
  1748.     Related commands: *Move, *Reverse.
  1749.     ================
  1750.  
  1751.  
  1752.     Note: The two memory blocks should not overlap, as this will
  1753.           generate an error. Swapping overlapped memory blocks causes
  1754.           the data in both blocks to be corrupted.
  1755.  
  1756.     =======================================================================
  1757. 21: *Timing <start> [<end>|+<length> [<offset>]]
  1758.     =======================================================================
  1759.  
  1760.      This command is similar to *Mdump with an 'M' format, however, the dump
  1761.      also includes the ARM instruction timing.
  1762.      It is informative to know how quickly you can expect instructions to
  1763.      execute. This command gives the timing of all ARM instructions.
  1764.      As different ARM machines have different clock frequencies, the timing
  1765.      is not given in actual nano- or micro-seconds, instead it is given in
  1766.      terms of 'instruction cycles'. The 'clock cycle' is one tick of the
  1767.      crystal oscillator which drives the ARM.
  1768.      There are 3 types of instruction cycles used in an ARM machine:
  1769.  
  1770.      1. Sequential (s) cycles:
  1771.         Used when the ARM fetches instructions in a sequential order.
  1772.         For example, when the ARM is executing instructions with no
  1773.         interruption from branches and load/store operation.
  1774.         These cycles are one clock cycle per instruction cycle for RAM
  1775.         and two clock cycles for ROM.
  1776.      2. Non-sequential (n) cycles:
  1777.         Used when the ARM fetches instructions in a non-sequential order.
  1778.         For example, the first instruction fetched after a branch
  1779.         instruction.
  1780.         These cycles need two clocks cycles per instruction cycle for RAM
  1781.         and ROM.
  1782.      3. Internal (i) cycles:
  1783.         Used when the ARM is performing an internal operation and not
  1784.         accessing memory to fetch an instruction.
  1785.         These instruction cycles always take one clock cycle.
  1786.  
  1787.      The actual time for each instruction to execute depends on the type
  1788.      of instruction and on the machine clock speed.
  1789.  
  1790.      The clock cycles timings are as follows:
  1791.  
  1792.       8 MHz machine: one clock cycle is 125 nano-seconds
  1793.      12 MHz machine: one clock cycle is 83.3 nano-seconds
  1794.      24 MHz machine: one clock cycle is 41.7 nano-seconds
  1795.      32 MHz machine: one clock cycle is 32.75 nano-seconds
  1796.  
  1797.      One nano-second equals one thousands of a micro-second.
  1798.  
  1799.      On an 8 MHz machine one 's' instruction cycle takes 125 nano-seconds,
  1800.      one 'n' cycle takes 250 nano-seconds.
  1801.      On a 16 MHz machine one 's' instruction cycle takes 65.5 nano-seconds.
  1802.      On 25 MHz and above machines the 's' and 'n' instruction cycle timing
  1803.    0 will be affected by the memory access time as the processor will be
  1804.      using wait states when accessing the slow memory. However, the 'i'
  1805.      cycles are not affected by memory access time.
  1806.  
  1807.  
  1808.     =======================================================================
  1809. 22: *Where <address>
  1810.     =======================================================================
  1811.  
  1812.     Purpose: Display the area of memory to which the given address 
  1813.     ======== belongs.
  1814.  
  1815.  
  1816.     Examples:
  1817.     =========
  1818.  
  1819.     *where 0            The command output will be 'OS workspace'
  1820.  
  1821.     *where 3400000      The command output will be 'Low ROM/VIDC'
  1822.  
  1823.     
  1824.  
  1825.    Possible errors: 'Bad number'
  1826.    ================ 'Bad memory'
  1827.  
  1828.    Related commands: *Mpage
  1829.    =================
  1830.  
  1831.  
  1832.  
  1833.                   ++++++++++++++++++++++++++++++++
  1834.                   +     General Commands          +
  1835.                   ++++++++++++++++++++++++++++++++
  1836.  
  1837.  
  1838.     =======================================================================
  1839.  1: *BList <filename> [<1st line>][,[<2nd line>]] [<LISTO number>]
  1840.     =======================================================================
  1841.  
  1842.     Purpose: Lists a tokenised BASIC file. Output is sent to the
  1843.     ======== screen but if VDU2 was issued output will also be sent to
  1844.              the printer.
  1845.  
  1846.     Parameters:
  1847.     ===========
  1848.  
  1849.     <filename>          the name of a BASIC tokenised file
  1850.     [<LISTO number>]    this is a number from 0-31. This is similar
  1851.                         to BASIC's LISTO option number except that
  1852.                         bit 1 (i.e. ident structure) is not used.
  1853.                         The default number is zero.
  1854.  
  1855.     LISTO option bits mean:
  1856.     bit 0: Space after line
  1857.     bit 1: Not used
  1858.     bit 2: Split lines at :
  1859.     bit 3: Don't list line numbers
  1860.     bit 4: List tokens in lower case
  1861.  
  1862.     Examples:
  1863.     ========
  1864.  
  1865.     *BList Prog          Lists file 'Prog' in default LISTO option.
  1866.  
  1867.     *BList Prog 1000     Lists line 1000 of file 'Prog'
  1868.  
  1869.     *Blist Prog 5000,    Lists file 'Prog' starting at line 5000.
  1870.                          Note: There should be no space between the
  1871.                          number and the comma.
  1872.  
  1873.     *Blist Prog 10,1000  Lists lines 10 through 1000 of file 'Prog'.
  1874.                          Note: There should be no space between the
  1875.                          the two numbers and the comma.
  1876.  
  1877.     *Blist Prog ,1000    Lists file 'Prog' from start up to line 1000.
  1878.  
  1879.     *Blist Prog ,1000 8  Lists file 'Prog' from start up to line 1000
  1880.                          without line numbers.
  1881.  
  1882.     NOTE: To specify the LISTO option, the 2nd line number must also be
  1883.           given otherwise the LISTO number is interpreted as the 1st line
  1884.           number.
  1885.  
  1886.  
  1887.     Possible errors: 'Not a BASIC file'
  1888.     ===============  'Bad BASIC file'
  1889.                      'Bad parameters'
  1890.  
  1891.     Related commands: None.
  1892.     ================
  1893.  
  1894.  
  1895.     =======================================================================
  1896.  2: *Event [<event number> <ON|OFF>]
  1897.     =======================================================================
  1898.  
  1899.     Purpose: Allow control and display of events status.
  1900.     ========
  1901.  
  1902.     Parameters:
  1903.     ===========
  1904.  
  1905.     <event number>         Decimal number 0 to 17
  1906.  
  1907.     <ON|OFF>               Enable or disable.
  1908.  
  1909.     Examples:
  1910.     =========
  1911.  
  1912.     *Event                Lists all events numbers, names and
  1913.                           status.
  1914.  
  1915.     *event 0 ON           Enable the output buffer empty event.
  1916.  
  1917.     *event 0 OFF          Disable the output buffer empty event.
  1918.  
  1919.  
  1920.     Possible errors: Bad parameter
  1921.     ================ Number too big
  1922.  
  1923.     Related commands: None.
  1924.     =================
  1925.  
  1926.     Generating events all the time uses a lot of processor time. To
  1927.     avoid this, events are disabled by default.
  1928.     In RISC OS 3, event number 11 (A key has been pressed or released
  1929.     event) is normally enabled. This is enabled by the Screen blanker
  1930.     module.
  1931.  
  1932.  
  1933.  
  1934.     =======================================================================
  1935.  3: *Index
  1936.     =======================================================================
  1937.  
  1938.     Purpose: Show the speed index of the machine.
  1939.     ====½===
  1940.  
  1941.     This command measures the speed index of the machine relative
  1942.     to an Archimedes A310 computer fitted with ARM 2 processor and
  1943.     a normal MEMC chip (i.e. not MEMC1a) operating in screen mode 0.
  1944.     In other words; this index gives a relative measure of how fast
  1945.     your computer is compared to a very early module of the
  1946.     Archimedes (in fact the first produced type 1987).
  1947.  
  1948.     NOTE:  This test will be extended in the future to cover other
  1949.     =====  aspects of the machine.
  1950.  
  1951.  
  1952.  
  1953.  
  1954.  
  1955.     =======================================================================
  1956.  4: *Labels
  1957.     =======================================================================
  1958.  
  1959.     Purpose: List all defined labels in memory.
  1960.     ========
  1961.  
  1962.     This command will list all currently defined labels in memory.
  1963.     This command will not list any defined remarks.
  1964.  
  1965.     The list shows the label address and name.
  1966.  
  1967.  
  1968.     Possible errors: No defined labels
  1969.     ================
  1970.  
  1971.     Related commands: *SaveLabels, *LoadLabels
  1972.     =================
  1973.  
  1974.     =======================================================================
  1975.  5: *LoadLabels <filename>
  1976.     =======================================================================
  1977.  
  1978.     Purpose: Loads a previously saved Labels file.
  1979.     ========
  1980.  
  1981.     This command is a complement to the *SaveLabels command, and
  1982.     allows you load any saved labels into ARCTOOLS buffer.
  1983.     If the file is larger than the current size of the Labels
  1984.     buffer, ARCTOOLS will try to extend the buffer area by claiming
  1985.     the adjacent free slot in the RMA. If this fails the file will
  1986.     not be loaded and an error message will be generated.
  1987.  
  1988.     Warning: Loading a Labels file will delete any currently
  1989.              defined labels in memory.
  1990.  
  1991.  
  1992.     Possible errors: Not a labels' file
  1993.     ================ Unable to extend due no room in RMA
  1994.  
  1995.     Related commands: *SaveLabels, *Labels.
  1996.     =================
  1997.  
  1998.  
  1999.     =======================================================================
  2000.  6: *Mcommands [<relocatable module name>]
  2001.     =======================================================================
  2002.  
  2003.     Purpose: List a given module *Command entry addresses.
  2004.     ========
  2005.  
  2006.     This command is used to list all commands in a given module
  2007.     together with their entry addresses.
  2008.     If no module name is given then all commands in the machine
  2009.     are listed.
  2010.  
  2011.  
  2012.     Parameters:
  2013.     ===========
  2014.  
  2015.     [<relocatable module name>]      Optional module name.
  2016.  
  2017.     Examples:
  2018.     =========
  2019.  
  2020.     *Mcommands ARCTOOLS          Lists all entry addresses of ARCTOOLS
  2021.                                  commands.
  2022.  
  2023.     *Mcommands Utility.          Lists all entry addresses of the Utility
  2024.                                  Module commands.
  2025.  
  2026.     *Mcommands                   Lists all entry addresses of all commands
  2027.                                  in the machine.
  2028.  
  2029.     Possible errors: Module not found
  2030.     ================
  2031.  
  2032.     Related commands: None.
  2033.     =================
  2034.  
  2035.  
  2036.     =======================================================================
  2037.  7: *SaveArc <filename>
  2038.     =======================================================================
  2039.  
  2040.     Purpose: Save ARCTOOLS module together with current
  2041.     ======== configurations.
  2042.  
  2043.     This command is used to save ARCTOOLS module to disc together
  2044.     with any configurations that you have made. Once loaded, the
  2045.     new ARCTOOLS module will remember the last disc and memory editors,
  2046.     the last memory address, the last disc address, the last flags
  2047.     setup in any editor.
  2048.     This is the easiest way of configuring your ARCTOOLS to suit your
  2049.     requirement. No fiddling with *Configure commands.
  2050.     
  2051.     
  2052.     Possible errors: None.
  2053.     ================
  2054.  
  2055.     Related commands: None.
  2056.     =================
  2057.  
  2058.     =======================================================================
  2059.  8: *SaveLabels <filename>
  2060.     =======================================================================
  2061.  
  2062.     Purpose: Save all defined labels in memory as a Data file.
  2063.     ========
  2064.  
  2065.     Once you have defined any labels in the memory editors, you
  2066.     can save them to disc as a Data file so that you will not
  2067.     have to write them all over again.
  2068.     It is also advisable to save any defined labels you have
  2069.     created before issuing any of the destructive modules
  2070.     *commands such as *Tidy, *Rmkill or *Rmclear.
  2071.  
  2072.     The saved labels can be loaded into ARCTOOLS buffer using the
  2073.     *LoadLabels command.
  2074.  
  2075.     Note: This command will also save any defined line comments.
  2076.  
  2077.  
  2078.     Possible errors: No defined labels
  2079.     ================
  2080.  
  2081.     Related commands: *LoadLabels, *Labels.
  2082.     =================
  2083.  
  2084.  
  2085.  
  2086.     =======================================================================
  2087.  9: *Slow [<value>]
  2088.     =======================================================================
  2089.  
  2090.     Purpose: Slow down program execution speed.
  2091.     ========
  2092.  
  2093.     This command slows down the machine by a given delay. Although
  2094.     this might seem strange thing you want your computer to do,
  2095.     you may need this command when you want to see things that are
  2096.     too quick for the eye to catch. Examples are, slowing down games
  2097.     so that you can play them at your own pace, watching the desktop
  2098.     window drawing order, debugging a program which outputs to the
  2099.     screen.
  2100.     Routines or programs that disable interrupts will not be slowed
  2101.     down, for example, you will not be able to actually see in slowmotion
  2102.     how a character is drawn on the screen pixel-by-pixel.
  2103.  
  2104.     Parameters:
  2105.     ===========
  2106.  
  2107.     [<value>]          This is the only parameter, which gives the
  2108.                        delay value in decimal numbers.
  2109.                        Acceptable values are 0 to 5120.
  2110.                        A value of 0 restores the machine to its own
  2111.                        speed.
  2112.     Examples:
  2113.     =========
  2114.  
  2115.     *Slow 200          Slow down the machine by a value of 200.
  2116.  
  2117.     *Slow 3000         Slow down by 3000. Very sluggish.
  2118.  
  2119.  
  2120.     Possible errors:  'Bad number'
  2121.     ================  'Number too big'
  2122.  
  2123.     Related commands:  None.
  2124.     =================
  2125.  
  2126.  
  2127.     =======================================================================
  2128. 10: *SwiC [<SWI chunck>]
  2129.     =======================================================================
  2130.  
  2131.     Purpose:  List all Software Interrupts in a given SWI Chunck
  2132.     ========  Identification number.
  2133.  
  2134.     The Operating System provides a total of 16 million different
  2135.     Software Interrupts or SWI. A SWI Chunck Identification
  2136.     number identifies a block of 64 consecutive SWIs. Acorn
  2137.     assigns a Chunck Identification number to each module or
  2138.     application on  request.
  2139.     The *SwiC command will list all SWIs in the given chunck
  2140.     identification number.
  2141.     If the number given is not a SWI chunck ID number it will be
  2142.     rounded to the related Chunck ID number.
  2143.     Because not every number in a SWI chunck is utilized, this
  2144.     command will only list used SWIs that have a SWI name.
  2145.  
  2146.     Examples:
  2147.     =========
  2148.  
  2149.     *SWIC 0            Lists all SWI numbers from 0 to 63
  2150.  
  2151.     *SWIC 40080        Lists all Font SWIs.
  2152.  
  2153.     *SWIC 43040        Lists all Territory SWIs.
  2154.  
  2155.     *SWIC 44B00        Lists all DOS filing system SWIs.
  2156.  
  2157.     Possible errors: Bad number
  2158.     ================
  2159.  
  2160.     Related commands: *SwiM, *SwiN, *SwiS
  2161.     =================
  2162.  
  2163.     =======================================================================
  2164. 11: *SwiM <relocatable module name>
  2165.     =======================================================================
  2166.  
  2167.     Purpose: List all Software Interrupts in a given module.
  2168.     ========
  2169.  
  2170.     Parameters:
  2171.     ===========
  2172.  
  2173.     <relocatable module name>    The module name, abbreviated if
  2174.                                  required.
  2175.  
  2176.     Examples:
  2177.     =========
  2178.  
  2179.     *SwiM  ADFS           Lists all SWIs in the ADFS module.
  2180.  
  2181.     *SwiM  Hour.          Lists all SWIs in the Hourglass module.    
  2182.  
  2183.     *SwiM  Squash         Lists all SWIs in the Squash module.
  2184.  
  2185.     *SwiM  UtilityModule  Lists all the Operating System SWIs.
  2186.  
  2187.     If the module does not have any SWIs then the 'No SWIs in module'
  2188.     message will be shown.
  2189.  
  2190.     Although the UtilityModule does not have SWIs, this commands will
  2191.     show all the Operating System SWIs (i.e SWIs with bits 18 and 19
  2192.     clear).
  2193.  
  2194.     Possible errors: Module not found
  2195.     ================
  2196.  
  2197.     Related commands: *SwiC, *SwiN, *SwiS.
  2198.     =================
  2199.  
  2200.  
  2201.     =======================================================================
  2202. 12: *SwiN <SWI name>
  2203.     =======================================================================
  2204.  
  2205.     Purpose: Convert a SWI name into a SWI number.
  2206.     ========
  2207.  
  2208.     Parameters:
  2209.     ===========
  2210.  
  2211.     <SWI name>         A valid SWI name.
  2212.  
  2213.     Examples:
  2214.     =========
  2215.  
  2216.     *SwiN   OS_Write0
  2217.  
  2218.     *SWIN   XOS_ReadC
  2219.  
  2220.  
  2221.     Note: The SWI name is case sensitive, and must be entered correctly.
  2222.  
  2223.  
  2224.     Possible errors: SWI name not known.
  2225.     ================
  2226.  
  2227.     Related commands: *SwiC, *SwiM, *SwiS
  2228.     =================
  2229.  
  2230.     =======================================================================
  2231. 13: *SwiS <SWI number>
  2232.     =======================================================================
  2233.  
  2234.     Purpose: Convert a SWI number into a SWI name.
  2235.     ========
  2236.                 
  2237.     Parameters:
  2238.     ===========
  2239.  
  2240.     <SWI number>         Hexadecimal SWI number.
  2241.  
  2242.     Examples: 
  2243.     =========
  2244.  
  2245.     *SWIS  0
  2246.  
  2247.     *SWIS  40
  2248.  
  2249.     *SWIS  80682
  2250.  
  2251.  
  2252.     Possible errors: Bad number
  2253.     ================
  2254.  
  2255.     Related commands: *SwiC, *SwiM, *SwiN
  2256.     =================
  2257.  
  2258.  
  2259.     =======================================================================
  2260. 14: *System
  2261.     =======================================================================
  2262.  
  2263.     Purpose: Display information on the current system and
  2264.     ======== program environment.
  2265.  
  2266.     The command displays information on the current system and the current
  2267.     environment, such as the processor type, memory used, memory limits, and
  2268.     all environment handlers codes addresses and buffers.
  2269.     The command also displays the application start time and the
  2270.     keyboard handler address. If an ARM3 or higher is fitted, then the
  2271.     current content of the cache control registers is shown.
  2272.     the *System command provides information on the following:
  2273.  
  2274.     - Processor type
  2275.     - Cache state (ON or OFF)
  2276.     - Cache ID register content
  2277.     - Cache Control register content
  2278.     - Cache Cacheable register content
  2279.     - Cache Updateable register content
  2280.     - Cache Disruptive register content
  2281.     - Memory limit address        
  2282.     - Undefined instructions handler address
  2283.     - Prefetch abort handler address
  2284.     - Data abort handler address
  2285.     - Address exception handler address
  2286.     - Error handler address
  2287.     - Error buffer address
  2288.     - CallBack handler address
  2289.     - CallBack register save area address
  2290.     - BreakPoint handler address
  2291.     - BreakPoint register save area address
  2292.     - Escape handler address
  2293.     - Event handler address
  2294.     - Exit handler address
  2295.     - Unused SWI handler address
  2296.     - Exception registers buffer address
  2297.     - Application space
  2298.     - Currently active object address
  2299.     - UpCall handler address
  2300.     - Current MEMC state
  2301.     - *Command string address
  2302.     - Keyboard handler address
  2303.     - Application start time
  2304.  
  2305.     =======================================================================
  2306. 15: *Tools [G|D|M]
  2307.     =======================================================================
  2308.  
  2309.     Purpose: Display a summary of all ARCTOOLS *Commands names
  2310.     ======== and their correct syntax.
  2311.  
  2312.     Examples:
  2313.     =========
  2314.  
  2315.     *Tools        Lists all ARCTOOLS commands.
  2316.  
  2317.     *Tools D      Lists all ARCTOOLS disc and file commands.
  2318.  
  2319.     *Tools G      Lists all ARCTOOLS general commands.
  2320.  
  2321.     *Tools M      Lists all ARCTOOLS memory commands.
  2322.  
  2323.     Possible errors: None
  2324.     ===============
  2325.  
  2326.     Related commands: None
  2327.     ================
  2328.  
  2329.  
  2330.     =======================================================================
  2331. 16: *Vector [<vector number>]
  2332.     =======================================================================
  2333.  
  2334.     Purpose: Display information on the routines claiming the Software
  2335.     ======== Vectors.
  2336.  
  2337.     The information displayed are address of the routines, routine
  2338.     workspace start address (R12) and where the routine is located
  2339.     i.e. OS kernel, ADFS, etc. The display also gives the vector name.
  2340.  
  2341.     The allowed vectors numbers are 0 to 47.
  2342.  
  2343.     The Operating System keeps track of the vector chains in its workspace
  2344.     (the first 32 Kbytes of memory). The chain structure contains pointers
  2345.     to the vector claimants code and workspace.
  2346.  
  2347.     *Vector with no parameter will list all the vectors available.
  2348.  
  2349.     Examples:
  2350.     =========
  2351.  
  2352.     *Vector 1                 gives information on the errorV
  2353.  
  2354.     *Vector                   gives information on all vectors
  2355.  
  2356.  
  2357.  
  2358.     Possible errors: 'Number too big'
  2359.     ===============
  2360.  
  2361.     Related Commands: None
  2362.     ================
  2363.  
  2364.  
  2365.  
  2366.  
  2367.  
  2368.                       ===========================
  2369.                            The Memory Editors
  2370.                       ===========================
  2371.  
  2372.  A total of 7 different memory editors are provided in ARCTOOLS allowing
  2373.  limitless possibilities or editing different memory areas. The most power-
  2374.  ful of these is the Mnemonics editor or dis-assembler, see the sections
  2375.  on the assembler and disassembler for more details.
  2376.  
  2377.   There are two methods to enter the memory editors:
  2378.  
  2379.   1. from the line command using the *Medit command.
  2380.   2. from the disc editors using the CTRL-E key combination.
  2381.  
  2382.  The cursor keys are used for navigate around memory. Facilities are provided
  2383.  to navigate really quickly using the 'Memory Area' jump. 'Memory Area' jumps
  2384.  can be achieved using the Up and Down cursor keys while holding the CTRL
  2385.  and SHIFT keys.
  2386.  
  2387.  The information bar (the top line of the screen) provides information on
  2388.  the current area and the current system as well as the current editor.
  2389.  The different information provided by the information bar can be viewed
  2390.  using the CTRL-Copy keys.
  2391.  
  2392.  Data can be entered in different formats depending on the editor type.
  2393.  The 'Text Editor' allows any character to be entered. In the 'Numbers'
  2394.  editor, only numbers are allowed. In the 'Hex', 'Bytes', 'Binary' and
  2395.  'Words' editors, you have the option of entering data using Hex, Binary,
  2396.  Decimal or Text formats, the different formats are selectable using the
  2397.  CTRL-Insert key.
  2398.  
  2399.  Two memory areas can not be edited; the ROM and the IO space. Other areas
  2400.  including the physical ram area can be edited.
  2401.  
  2402.  
  2403.  
  2404.  
  2405.  
  2406.  
  2407.  
  2408.                       ===========================
  2409.                             The DISC Editors
  2410.                       ===========================
  2411.  
  2412.   ARCTOOLS provides a number of powerful tools to manipulate data stored
  2413.   on discs directly. The *Dget and *Dput commands are one example of
  2414.   an improved method of moving data between disc and memory which removes
  2415.   the Operating System limitations of having to work with sector aligned
  2416.   start addresses and sizes. The most powerful tool provided by ARCTOOLS
  2417.   is the disc editor. The disc editor manipulates data stored on discs
  2418.   directly using disc addresses rather than sector and track numbers.
  2419.   Seven different display formats are provided, similar to those in the
  2420.   memory editors, this gives a total of seven disc editors. The disc editors
  2421.   provide additional information on the currently editted disc which is
  2422.   displayed at the top line of the screen using the CTRL-Copy key
  2423.   combination.
  2424.   
  2425.   There are two methods to enter the disc editors:
  2426.  
  2427.   1. from the line command using the *Dedit command.
  2428.   2. from the memory editor using the CTRL-E key combination.
  2429.  
  2430.   The disc editors work with any disc format known to the Operating System.
  2431.   Under RISC OS this includes:
  2432.   - ADFS disc formats L, D, E and F.
  2433.   - DOS 1.44M, 720M, 1.2M and 360K discs.
  2434.   - Atari 720K and 360K discs.
  2435.   - RAM discs.
  2436.   - IDE hard discs.
  2437.   - ST506 hard discs.
  2438.   - SCSI hard discs.
  2439.  
  2440.   The disc editors will automatically support any new filing systems added
  2441.   to the FileCore modules.
  2442.  
  2443.   WARNING:     Extreme care must be observed when using the disc editors.
  2444.   ========     The entire disc can be accessed and any data can be changed
  2445.                without restriction. Changing data on the disc particularly
  2446.                directory or map data can render large number of files and
  2447.                or the entire disc inaccessible.
  2448.  
  2449.  
  2450.   Using the Disc Editors with non-standard discs:
  2451.   ===============================================
  2452.  
  2453.   The disc editors also support non-standard or protected format discs. The
  2454.   format of these discs must be described to ARCTOOLS disc editors. To
  2455.   achieve this a simple method is used.
  2456.  
  2457.   When any of the disc editors is entered, ARCTOOLS asks the Operating
  2458.   System to identify the disc format. If the Operating System or its
  2459.   extension modules fail to identify the disc and error message will be
  2460.   produced which prevents you from using the disc editors.
  2461.   To allow non-standard discs to be edited, ARCTOOLS must first be told
  2462.   that the format is non-standard. Do this proceed as follows:
  2463.  
  2464.   1. Insert a known format disc in the required drive.
  2465.   2. Enter the disc editor.
  2466.   3. Remove the known format disc and insert the non-standard disc.
  2467.      At this time the sector content shown on the screen is still
  2468.      that of the previous known format disc.
  2469.   4. Press CTRL-SHIFT-I (Hold down CTRL and SHIFT keys and press I).
  2470.      A simple menu on the bottom of the screen is shown. This menu
  2471.      shows the previous disc format total tracks, sectors per track,
  2472.      sector size, total heads and disc density.
  2473.      Use the right and left cursor keys to move through the different
  2474.      parameters, and the Up and down keys to modify these parameters.
  2475.   5. Once you have setup the new format press the RETURN key. The disc
  2476.      will now be accessed using the format that you have just setup.
  2477.  
  2478.  
  2479.   Recovering deleted files using the Disc Editors:
  2480.   ================================================
  2481.  
  2482.   Unlike other filing system, the ADFS is one of the most difficult when
  2483.   it comes to recovering deleted files. Accidently deleting files is
  2484.   a common mistake many users do. On some filing system, for example,
  2485.   the DOS filing system it is much much easier to recover these files.
  2486.   The reason behind this is in the way the ADFS deletes the files.
  2487.   When you request a file to be deleted using the *Delete or *Wipe command,
  2488.   the ADFS removes the file name and its information from the directory
  2489.   space on the disc, then it returns the space allocated to it to the
  2490.   disc free space map so that this free space can be used for storing
  2491.   other files. The data in the free space is not destroyed as long as
  2492.   it is not overwritten by another file. What makes recovering deleted
  2493.   files difficult on the ADFS is that the file name and its information
  2494.   are wiped out. The DOS filing system, for example, does not wipe out
  2495.   the filename or its information data. It simply replaces the first
  2496.   character of the filename with a control code &E5.
  2497.   Given the above information it is impossible to write programms that
  2498.   provide facilites such as the 'UnErase' Norton Utility on DOS systems.
  2499.  
  2500.   Recovering deleted files on the ADFS is unfortunately a manual method.
  2501.   Geared with information on the lost file, the user has to search the
  2502.   disc to locate the start and end addresses of the file. On a disc with
  2503.   an E or F format, the file could be fragmented and its content is
  2504.   scattered all over the disc surface.
  2505.  
  2506.   ARCTOOLS provides the following manual methods:
  2507.  
  2508.   - You can search for a given string in the lost file. This speeds up the
  2509.     search process.
  2510.   - You can use the 'Nex Free Map' option. Using the CTRL-SHIFT-UP cursor
  2511.     or Down cursor, you can search for the deleted file in the free sectors.
  2512.     This is the place where your deleted file resides.
  2513.   - Once identified you can use the disc marks to mark the start and end
  2514.     addresses of the file, then copy this data to memory using the
  2515.     'Command menu'.
  2516.   - Once in memory the data can be saved to file using the 'Commands Menu'.
  2517.  
  2518.   With fragmented files, each fragment has to be saved seperately and then
  2519.   using the *Fjoin command the files can joined together (in the correct
  2520.   order).
  2521.  
  2522.  
  2523.   Writing back edited data:
  2524.   =========================
  2525.  
  2526.   When editing sector data, the data is written into a copy of the sector
  2527.   in memory and not immediately stored on disc. After a sector's data has
  2528.   been changed, moving onto another sector or track or exiting the editor
  2529.   will cause the message 'Save Sector [Y/N] ?' to appear. Pressing the
  2530.   'Y' key will cause the sector data to be written back to disc. Any other
  2531.   key will skip the sector saving routine.
  2532.  
  2533.   Errors when reading a disc:
  2534.   ===========================
  2535.  
  2536.   If errors are encountered when ARCTOOLS is reading data from a disc,
  2537.   an error message will be generated. The sector content displayed on the
  2538.   screen will be shown as a text message 'Bad'.
  2539.   
  2540.  
  2541.  
  2542.                      ============================     
  2543.                           The commands Menu
  2544.                      ============================
  2545.  
  2546. The commands menu is built into all memory and disc editors. The menu
  2547. can be called by pressing the key combination CTRL+C providing both
  2548. memory marks (in the memory editors) or disc marks (in the disc editors)
  2549. have been set.
  2550. The commands menu shows a list of itmes which can be selected using the
  2551. UP and Down cursor keys.
  2552. The two memory marks are used for various operations. Some operations
  2553. require a third address, for example, the MOVE MEMORY command. The 3rd
  2554. address will be the current memory address before the commands menu
  2555. is entered. The 3rd address can be changed.
  2556. Some commands will execute when you simply hit the return key, for example,
  2557. the 'Wipe memory' option. Other options require a string or numbers to
  2558. be entered. In this case you should enter the required parameter and hit
  2559. return.
  2560. At any time while entering a value, you can use the UP and DOWN cursors
  2561. to ignore the current command and go to the next command or option.
  2562. The commands menu will be exited if you hit the Escape key, or after a
  2563. command is executed.
  2564.  
  2565. Commands menu options:
  2566. ======================
  2567.  
  2568.  1. Move Memory:  Move address1 address2 to [address3]
  2569.  
  2570.     address1 and address2 are the start and end addresses of the memory
  2571.     area set using mark1 and mark2.
  2572.     address3 is the current memory address. This can be changed.
  2573.     This will move the marked area to the address given in address3.
  2574.     
  2575.  2. Swap Memory:  Swap address1 address2 with [address3]
  2576.  
  2577.     address1 and address2 are the start and end addresses of the memory
  2578.     area set using mark1 and mark2.
  2579.     address3 is the current memory address. This can be changed.
  2580.     This will swap the marked area with the area starting at address3.
  2581.  
  2582.  
  2583.  3. Wipe      : Wipe address1 address2 ? <Return to execute>
  2584.                 Wipe current sector? <Return to execute>
  2585.  
  2586.     address1 and address2 are the start and end addresses of the memory
  2587.     area set using mark1 and mark2.
  2588.     Hitting the Return key will cause the area to be wiped clean.
  2589.     In the disc editors this menu option will wipe the current sector.
  2590.  
  2591.  4. Memory ---> File : Save address1 address2 filename: [_              ]
  2592.  
  2593.     address1 and address2 are the start and end addresses of the memory
  2594.     area set using mark1 and mark2.
  2595.     Enter the filename to save under, then press Return. This will save
  2596.     the content of the memory area as a 'Data' file.
  2597.  
  2598.  
  2599.  5. File ---> Memory : Load to address1 address2 filename: [_           ]
  2600.  
  2601.     address1 and address2 are the start and end addresses of the memory
  2602.     area set using mark1 and mark2.
  2603.     This command will load a file into the given memory area. If the file
  2604.     size is larger then the size of the memory area, then the following
  2605.     message will be shown:
  2606.     File too large by xxxx bytes. <Load/Insert> (L/I)?
  2607.     You are offered the option whether to Insert the file or to Load the
  2608.     complete file. Inserting the file into the given memory area will
  2609.     load only the part which will fit into the given area.
  2610.  
  2611.  
  2612.  
  2613.  6. Fill Bytes : Fill address1 address2 with bytes [_                   ]
  2614.                  Fill current sector with bytes [_                    ]
  2615.  
  2616.     address1 and address2 are the start and end addresses of the memory
  2617.     area set using mark1 and mark2.
  2618.     This command is similar to the *FillH command. You can enter the
  2619.     sequence of bytes (hex) to fill memory with.
  2620.     In the disc editors, this option will fill the current sector with
  2621.     a sequence of bytes.
  2622.  
  2623.  
  2624.  7. Fill Words : Fill address1 address2 with words [_                   ]
  2625.                  Fill current sector with words [_                    ]
  2626.  
  2627.     address1 and address2 are the start and end addresses of the memory
  2628.     area set using mark1 and mark2.
  2629.     This command is similar to the *FillW command. You can enter the
  2630.     sequence of words to fill memory with.
  2631.     In the disc editors, this option will fill the current sector with
  2632.     a sequence of words.
  2633.  
  2634.  8. Fill String : Fill address1 address2 with string [_                 ]
  2635.                   Fill current sector with string [_                   ]
  2636.  
  2637.     address1 and address2 are the start and end addresses of the memory
  2638.     area set using mark1 and mark2.
  2639.     This command is similar to the *FillT command. You can enter the
  2640.     string to fill memory with.
  2641.     In the disc editors, this option will fill the current sector with
  2642.     the given string.
  2643.  
  2644.  9. Fill Mnemonic: Fill address1 address2 with mnem. [_                  ]
  2645.                    Fill current sector with mnem. [_                    ]
  2646.  
  2647.     address1 and address2 are the start and end addresses of the memory
  2648.     area set using mark1 and mark2.
  2649.     This command will fill the given memory with the entered Mnemonic
  2650.     string.
  2651.     In the disc editors, this option will fill the current sector with
  2652.     the given mnemonic string.
  2653.  
  2654. 10. Disc ---> Memory: Get disc address1 address2 to memory [address3]
  2655.  
  2656.     address1 and address2 are the start and end addresses of the Disc
  2657.     area set using mark1 and mark2 when in the disc editors.
  2658.     If the commands menu was called from a disc editor then address3
  2659.     will be the start of the memory area. If it was called from within
  2660.     the memory editors, then address3 will be the current memory address.
  2661.     This command will copy the disc area marked by address1 and address2
  2662.     to the memory area starting at address3.
  2663.  
  2664. 11. Memory ---> Disc: Put memory address1 address2 to disc [address3]
  2665.  
  2666.     address1 and address2 are the start and end addresses of the memory
  2667.     area set using mark1 and mark2.
  2668.     If the commands menu was called from a disc editor then address3
  2669.     will be the current disc address. If it was called from within the
  2670.     memory editors, then address3 will be the start of the disc area.
  2671.     This command will copy the memory area marked by address1 and address2
  2672.     to the disc area starting at address3.
  2673.  
  2674.  
  2675. 12. Invert Memory: Invert address1 address2 ? <Return to execute>
  2676.  
  2677.     address1 and address2 are the start and end addresses of the memory
  2678.     area set using mark1 and mark2.    
  2679.     This command will reverse the memory area when Return key is pressed.
  2680.     It is similar to the *Reverse command.
  2681.  
  2682. 13. Label Area: Label area address1 address2 with [Label            ]
  2683.  
  2684.     address1 and address2 are the start and end addresses of the memory
  2685.     area set using mark1 and mark2.
  2686.     This command will auto label the area given in address1 and address2.
  2687.     Label names will start with the string 'Label', however this can
  2688.     be changed to any string. All labels will be counted from 0 and
  2689.     attached to label names. For example, Lable_0, Label_1, Label_2...
  2690.     If ARCTOOLS can not find any labels in the given area, the message:
  2691.     'No labels in this area' will be generated.
  2692.  
  2693.  
  2694.                          ====================
  2695.                          Keys used in Editors
  2696.                          ====================
  2697.  
  2698. ARCTOOLS EDITOR KEYS Summarys:
  2699. ==============================
  2700.  
  2701. Escape                :Abandon current operation, return to last activity.
  2702. CTRL+Escape           :Exit the editor, dumping the current line to screen.
  2703. CTRL+B                :Enter BINARY editor
  2704. CTRL+H                :Enter HEX editor
  2705. CTRL+W                :Enter WORDS editor
  2706. CTRL+N                :Enter NUMBERS editor
  2707. CTRL+M                :Enter MNEMONIC editor
  2708. CTRL+T                :Enter TEXT editor
  2709. CTRL+Y                :Enter BYTEs editor
  2710.  
  2711. CTRL+J                :JUMP to branch-to address (MNEMONIC editor only)
  2712. CTRL+SHIFT+J          :JUMP to address in current memory address
  2713.                        or to address in current memory address plus offset
  2714.                        in Mark1 if Mark1 is set
  2715. CTRL+R                :Return to previous address
  2716. CTRL+G                :Goto address
  2717.  
  2718. CTRL+F                :Find data. Search for data in memory.
  2719. CTRL+Back space       :Continue search from current address
  2720. CTRL+SHIFT+Back space :Continue search from last found address
  2721. CTRL+TAB              :Toggle text search case sensitivity
  2722.  
  2723. CTRL+L                :Label the current memory address
  2724. CTRL+SHIFT+L          :Comment on the current memory address
  2725.  
  2726.  
  2727. CTRL+X                :Toggle top bit of ASCII codes
  2728. CTRL+P                :Dump screen to PRINTER
  2729. CTRL+D                :Toggle between Active and Passive screen DISPLAY
  2730.  
  2731. CTRL+S                :In BINARY editor: Toggle between 8 or 32 bit
  2732.                                          position count
  2733.                       :In NUMBERS editor:Change SIGN of number
  2734. CTRL+COPY             :Change Screen Information Bar.
  2735. CTRL+INSERT           :Change Data entry format
  2736.                       :In NUMBERS editor:Change number padding ASCII code
  2737.  
  2738. CTRL+keypad 1         :Set Mark No.1
  2739. CTRL+keypad 2         :Set Mark No.2
  2740. CTRL+HOME             :Goto Mark
  2741. CTRL+Delete           :Delete all marks
  2742.  
  2743. CTRL+C                :Enter Commands menu
  2744. CTRL+E                :Toggle between Memory and Disc EDITORS
  2745. CTRL+I                :Install new disc (DISC editors only)
  2746. CTRL+SHIFT+I          :Install user defined disc
  2747. CTRL+keypad *         :Enter *Command line
  2748.  
  2749. Right Cursor          :Move cursor one place right
  2750. Left Cursor           :Move cursor one place left
  2751. Up Cursor             :Move cursor up one line
  2752. Down Cursor           :Move cursor down one line
  2753.  
  2754. SHIFT+Right Cursor    :Move cursor to rightmost position.
  2755. SHIFT+Left Cursor     :Move cursor to leftmost position.
  2756. SHIFT+Up Cursor       :Move cursor Up 29 lines (one full screen).
  2757. SHIFT+DOWN Cursor     :Move cursor DOWN 29 lines (one full screen).
  2758.  
  2759. CTRL+Right Cursor     :In Memory Editors: Move cursor to rightmost position.
  2760.                        In Disc Editors  : Increment address by One SECTOR.
  2761. CTRL+Left Cursor      :In Memory Editors: Move cursor to leftmost position.
  2762.                        In DISC Editors  : Decrement address by One SECTOR.
  2763. CTRL+Up Cursor        :In Memory Editors: Go to start of previous memory
  2764.                                           page.
  2765.                        In Disc Editors  : Decrement address by One TRACK.
  2766. CTRL+DOWN Cursor      :In Memory Editors: Go to start of next memory page.
  2767.                        In Disc Editors  : Increment address by One TRACK.
  2768.  
  2769. CTRL+SHIFT+Up Cursor  :In Memory Editors:Go to start of previous memory area.
  2770.                        In Disc Editors  :Go to start of previous free disc
  2771.                                          space map area.
  2772.  
  2773. CTRL+SHIFT+DOWN Cursor:In Memory Editors:Go to start of next memory area.
  2774.                        In Disc Editors  :Go to start of next free disc space
  2775.                                          map area.
  2776.  
  2777.  
  2778.                    ARCTOOLS EDITORS KEYS description:
  2779.                    ==================================
  2780.  
  2781. Escape key:
  2782. -----------
  2783. The Escape key is used to abandon the current operation and return to the
  2784. last operation. Use Escape to:
  2785.  - exit the memory or disc editors, or
  2786.  - exit the commands menu, or
  2787.  - abandom any current operation.
  2788.  
  2789.  
  2790. CTRL+Escape (Exit the editor showing current address data on screen)
  2791. --------------------------------------------------------------------
  2792. Somtimes you may want to exit the editor after you have searched for
  2793. certain data. May be, you wanted to use this data in your BASIC program,
  2794. to do so, press CTRL+Escape keys, this will exit the current editor but
  2795. your data will be on the screen. Now you can copy it into a BASIC program
  2796. line or do some mathematical calculations on it using the BASIC
  2797. keywords.
  2798.  
  2799.  
  2800. CTRL+J  (Jump to address)
  2801. -------------------------
  2802. In the mnemonics editor, this key combination allows the user to perform
  2803. a "jump to address" which can be used to follow the structure of a
  2804. program. The address that the editor jumps to is the one at the current
  2805. cursor position and only when one of the following instructions is being
  2806. highlighted:
  2807.  
  2808.  B     {Address/Label}
  2809.  BL    {Address/Label}
  2810.  ADR   Rx,{Address/Label}
  2811.  ADRL  Rx,{Address/Label}
  2812.  STR   Rx,{Address/Label}
  2813.  LDR   Rx,{Address/Label}
  2814.  STF   Fx,{Address/Label}
  2815.  LDF   Fx,{Address/Label}
  2816.  STC   Cp#x,Cx,{Address/Label}
  2817.  LDC   Cp#x,Cx,{Address/Label} 
  2818.  
  2819. Example of CTRL+J use:
  2820. ----------------------
  2821. The following example allows you to examine the Operating System
  2822. Software Interrupt routine.
  2823.  
  2824. 1. Enter the mnemonic editor at location &00000008 which is the SWI
  2825.    hardware vector by typing: *MEDIT 8 M
  2826. 2. The instruction at memory location &8 is a branch instruction to
  2827.    the SWI decode routine. Press CTRL+J to go to the start of that
  2828.    routine.
  2829.  
  2830. Pressing CTRL+R will return you to the previous memory location where the
  2831. jump was made from. Jumps to addresses can be nested up to 255 jumps.
  2832. CTRL+J is only valid in the mnemonic editor. If you try to use it in any
  2833. other editor it will be ignored.
  2834.  
  2835. CTRL+R    (Return to last jumped from address)
  2836. ----------------------------------------------
  2837. This key combination allows you to return to the last jumped from address.
  2838. A beep is emitted if their are no more return addresses.
  2839.  
  2840.  
  2841. CTRL+SHIFT+J  (Jump to word address)
  2842. ------------------------------------
  2843. This key combination is only valid in the mnemonic editor.
  2844. This key combination allows the user to jump to a memory location which
  2845. is stored in the current highlighted memory location.
  2846. example: if the cursor is at the following location,
  2847.  
  2848.  01F033FC  .1..  03803104  ORREQ    R3,R0,#1
  2849.  
  2850. then pressing CTRL+SHIFT+J will cause the editor to jump to the memory
  2851. address at location store at &01F033FC which is in this case &03803104.
  2852.  
  2853. Another example:
  2854. The following example allows you to examine the Operating System SWIs
  2855. routines.
  2856. 1. Enter the mnemonic editor at location &00000008 which is the SWI
  2857.    hardware vector by typing: *MEDIT 8 M
  2858. 2. The instruction at memory location &8 is a branch instruction to
  2859.    the SWI decode routine. Press CTRL+J to go to the start of that
  2860.    routine.
  2861. 3. Move the cursor down 15 lines to move to the start of the Operating
  2862.    System Software Instructions Jump Table.
  2863.    The table contains jump addresses for all SWI routines used by the
  2864.    OS Kernel, i.e. SWI 0 through &1FF
  2865.    Memory address &1F033FC contains the value &3803104 which is the
  2866.    address for the "OS_WriteC".
  2867. 4. To jump to the "OS_WriteC" code which starts at &3803104, position
  2868.    the cursor to address &1F033FC, then ensure that Mark 1 is clear by
  2869.    pressing CTRL+Delete (See Offset Jumps). Once Mark 1 is cleared, press
  2870.    CTRL+SHIFT+J to jump to address &3803104. This is the 'OS_WriteC'
  2871.    Code.
  2872.  
  2873. Offset Jumps:
  2874. -------------
  2875. An additional feature of CTRL+SHIFT+J key combination is OFFSET jump.
  2876. The offset jump is automatically selected if MARK 1 is set. In this case,
  2877. before jumping to the address at current memory location, the editor will
  2878. add the address of MARK 1 to it.
  2879. This offset jump can be very helpful when examining module tables.
  2880. Example of offset jump:
  2881. The following example will take you the SWI handler code used in the
  2882. 'PDriver' module.
  2883.  
  2884. type the following:
  2885.  
  2886. *medit 391773C M
  2887. This will enter Mnemonic Editor at start of 'PDriver' module.
  2888.  
  2889. Note: The 'PDriver' module start address can be obtained by using the
  2890.       OS command '*Modules'
  2891.  
  2892. Press CTRL+ Keypad 1  to set mark no. 1. Mark 1 would be set to 391773C.
  2893. Move the cursor down until address 391775C is reached. This address
  2894. contains the value &1B0 which is the offset from the start of the module
  2895. to the module SWI handler code.
  2896. To jump to the SWI handler code simply press CTRL+SHIFT+J. The editor
  2897. will add the offset value (&1B0) contained at current memory location to
  2898. the address value stored in Mark 1 and jump to the result address.
  2899.  
  2900.  
  2901. NOTE: The above example of CTRL+J and CTRL+SHIFT+J assume a RISC OS 3
  2902.       operating system is fitted on an A5000.
  2903.  
  2904.  
  2905. CTRL+G    (Go to address or label)
  2906. ----------------------------------
  2907. This key combination allows you to move to another memory area very
  2908. quickly by giving the address or the label name. The given address
  2909. is assumed to be a hexadecimal number, any number base can be given.
  2910. ARCTOOLS remembers the memory address you have left, so to return to the
  2911. previous address after this command, press CTRL+R.
  2912.  
  2913.  
  2914. CTRL+F  (Find or Data Search)
  2915. -----------------------------
  2916. This key combination is used to locate data in memory or on disc.
  2917. The data type depends on the type of editor in use.
  2918. 1. In the TEXT editor:
  2919.    Searches for a string. single wildcards are allowed
  2920. 2. In the Binary editor:
  2921.    Searches for a binary number. single wildcards are allowed
  2922. 3. In the Hex editor:
  2923.    Searches for hex numbers. single wildcards are allowed
  2924. 4. In the Word editor:
  2925.    Searches for a word. single wildcards are allowed
  2926. 5. In the Numbers editor:
  2927.    Searches for a decimal number. No wildcards allowed
  2928. 6. In the Mnemonic editor:
  2929.    Searches for an ARM, FPU or CO-PRO instruction. No wildcards allowed
  2930.  
  2931. The search starts at the current memory address. Once data is found,
  2932. use CTRL+Back Space for the next match.
  2933. You can switch to a different editor and continue the search.
  2934.  
  2935.  
  2936. CTRL+Back Space (Continue search from current address)
  2937. ------------------------------------------------------
  2938. Continues the search for the data from the current memory address.
  2939. The 'Back Space' key is located to the right of the Pound sign key.
  2940.  
  2941.  
  2942. CTRL+SHIFT+Back Space (Continue search from last found address)
  2943. ---------------------------------------------------------------
  2944. Continues the search for the data from the last found address.
  2945.  
  2946.  
  2947. CTRL+TAB  (Toggle string search CASE)
  2948. -------------------------------------
  2949. Toggle between Case sensitive and case insensitive string search.
  2950. The CASE status can be viewed using the information title at the top
  2951. display screen using CTRL+Copy.
  2952. CASE: OFF  means case insensitive
  2953. CASE: ON  means case sensitive
  2954.  
  2955.  
  2956. CTRL+L (Label address)
  2957. ----------------------
  2958. This function is only available in the Mnemonic memory editor.
  2959. Used to label an address of memory. The current memory address is labelled.
  2960. If the current address already has a defined label, then, when this function
  2961. is entered, the label name will be displayed at the cursor position so
  2962. that this can be changed or deleted.
  2963. Maximum label string length is 23 characters.
  2964.  
  2965. To delete a previously defined label you should press CTRL+L at the
  2966. current label address, then use CTRL+U or the delete key to remove the
  2967. label name, then press enter. 
  2968.  
  2969. NOTE: Ensure that the assembler 'labels and remarks' flag is ON, so
  2970.       that the assembler can display any defined labels or remarks.
  2971.  
  2972. NOTE: If your enter a label name which is already defined, then that
  2973.       label name is removed and the current address is assigned to it.
  2974.  
  2975. NOTE: See the section on the Line Editor.
  2976.  
  2977.  
  2978. CTRL+SHIFT+L (Place a remark at an address)
  2979. -------------------------------------------
  2980. This function is only available in the Mnemonic memory editor.
  2981. The message 'Enter comment' will be shown at the current memory address.
  2982. Enter the remark or comment and press return.
  2983. A remark can be deleted by using CTRL+SHIFT+L on the remark address,
  2984. deleting the whole line, then pressing enter.
  2985.  
  2986.  
  2987. NOTE: See the section on the Line Editor.
  2988.  
  2989.  
  2990. CTRL+X    (Toggle ASCII top-bit)
  2991. --------------------------------
  2992. This key combinations is used to toggle the top-bit of ASCII characters
  2993. displayed on screen. With top bit clear, text strings are easy to read.
  2994.  
  2995.  
  2996. CTRL+P    (Print screen)
  2997. ------------------------
  2998. Sends the contents of the screen to printer. All Ascii characters are
  2999. sent to the printer with their top-bit clear.
  3000. You should have your printer on-line before pressing CTRL+P.
  3001.  
  3002. NOTE: ARCTOOLS (current version) does not check to see if your printer
  3003.       is on-line. The program will hang if your printer is not on line.
  3004.       This is to be corrected in the next version.
  3005.  
  3006.  
  3007. CTRL+D    (Toggle Display type)
  3008. -------------------------------
  3009. Toggles between active and passive display. When the display status is
  3010. ON, the locations of memory are constantly read and updated on the screen.
  3011. This type of active display allows the user to examine memory locations
  3012. which are constantly changing.
  3013. The status of display is displayed at the top of the screen using CTRL+Copy.
  3014. For example, try to examine memory area starting at &9A8 with active
  3015. display switched ON.
  3016.  
  3017.  
  3018. CTRL+S
  3019. ------
  3020. This key combination is only used in the Binary and the Numbers Editors.
  3021. In the Numbers editor: It is used to modify the memory content from a
  3022.                        a signed into unsigned number.
  3023. In the Binary editor : This is used to toggle between 32-bit or 8-bit
  3024.                        position count. The bit position count is
  3025.                        shown on the top right corner of the screen, so
  3026.                        that you can move the cursor to the required bit
  3027.                        position without having to count using your fingure!
  3028.                        This is normally 32-bit count (from 0 to 31), but
  3029.                        can be 8-bit count considering the 32-bit number
  3030.                        is split into four 8-bit bytes.
  3031.  
  3032.  
  3033. CTRL+Copy  (Information Bar display)
  3034. ------------------------
  3035. Cycles through the information bar which is shown at the top of the screen.
  3036.  
  3037. In the memory editors the following information is provided:
  3038.  
  3039. 1. ARCTOOLS Version number and author name
  3040. 2. Current memory area name and its size
  3041. 3. Current memory page information
  3042. 4. Machine total RAM size, total pages and page size
  3043. 5. Memory and Disc marks
  3044. 6. Display status, case status, Top bit status and current editor type
  3045.  
  3046. In the disc editors the following information is provided:
  3047.  
  3048. 1. ARCTOOLS Version number and author name
  3049. 2. Drive information:
  3050.    -Current drive number and type (Floppy or Hard),
  3051.    -Current head number,
  3052.    -Current sector number,
  3053.    -Current track number,
  3054. 3. Sectors information:
  3055.    -Total sectors per track,
  3056.    -Current sector number,
  3057.    -Sector size,
  3058.    -Sector start address
  3059. 4. Tracks information:
  3060.    -Total tracks per head,
  3061.    -Current track number,
  3062.    -Track size,
  3063.    -Track start address
  3064. 5. Drive information:
  3065.    -Total heads,
  3066.    -Total sectors per track,
  3067.    -Total tracks per head,
  3068.    -Density,
  3069.    -Root directory address
  3070. 6. Drive information:
  3071.    -Disc name,
  3072.    -Disc ID,
  3073.    -Disc size
  3074. 7. Memory and disc marks
  3075. 8. Display status, case status, Top bit status and current editor type.
  3076.  
  3077.  
  3078. The Memory and Disc marks are automatically displayed if any marks is
  3079. set or the Commands menu is entered.
  3080.  
  3081.  
  3082. CTRL+Insert  (Data Input)
  3083. -------------------------
  3084. Selects the type of data input format used when editing memory or disc.
  3085. The Data Input depends on the editor type as follows:
  3086.  
  3087. Binary Editor  : Binary, Hex, Decimal, Text.        Default: Binary
  3088. Hex Editor     : Binary, Hex, Decimal, Text.        Default: Hex
  3089. Text Editor    : Text only
  3090. Words Editor   : Binary, Hex, Decimal, Text.        Default: Hex   
  3091. Mnemonic Editor: Set or unset the current shown display format flag.
  3092. Numbers Editor : Numbers only
  3093. Byte Editor    : Binary, Hex, Decimal, Text.        Default: Decimal
  3094.  
  3095. In the Numbers editor CTRL+Insert is used to change the leading padding
  3096. character from zeros to spaces.
  3097.  
  3098.  
  3099. CTRL+Keypad 1 (Set Mark 1)
  3100. --------------------------
  3101. Sets Mark no.1 to the current memory address if in memory editors or
  3102. to to current disc address if in disc editors.
  3103. Mark 1 address is displayed on the top of the screen as "Memory: {address}"
  3104. or "Disc: {address}"
  3105.  
  3106. CTRL+Keypad 2 (Set Mark 2)
  3107. --------------------------
  3108. Sets Mark no.2 to the current memory address if in memory editors or
  3109. to to current disc address if in disc editors.
  3110. Mark 2 address is displayed on the top of the screen as "To: {address}"
  3111. or "To: {address}"
  3112.  
  3113.  
  3114. CTRL+Home (Go to set mark)
  3115. --------------------------
  3116. Pressing CTRL+Home keys will allow you to go to the address in the
  3117. set marks. First press takes you to mark1 address, the second press,
  3118. to mark2 address.
  3119.  
  3120.  
  3121. CTRL+Delete
  3122. -----------
  3123. Removes memory Mark1 and Mark2 if in memory editors.
  3124. Removes discs Mark1 and Mark2 if in disc editors.
  3125.  
  3126.  
  3127. CTRL+C   (Commands menu)
  3128. ------------------------
  3129. Enters the commands menu.
  3130. The commands menu can be entered from any memory or disc editor providing
  3131. both memory marks are set. See the Section on the Commands Menu for more
  3132. details.
  3133.  
  3134.  
  3135. CTRL+E   (Toggle between Memory and Disc editors)
  3136. -------------------------------------------------
  3137. This key combination is used to toggle between memory and disc editors.
  3138. In any memory editor, pressing CTRL+E will enter the Disc editor on
  3139. the last disc address viewed. Pressing CTRL+E in any disc editor will
  3140. take you back to the last visited memory address. This provides a quick
  3141. method of switching between the different editors without having to
  3142. revert to the *Medit and *Dedit commands.
  3143.  
  3144.  
  3145. CTRL+I (Install disc)
  3146. ---------------------
  3147. This key combination is only available in the disc editors.
  3148. This causes a new disc to be read by the editor. This allows the user
  3149. to examine a new disc without leaving the disc editor.
  3150. The editor will read information from the currently selected drive.
  3151.  
  3152.  
  3153. CTRL+SHIFT+I (Install user defined disc)
  3154. ----------------------------------------
  3155. This key combination is only available in the disc editors. This allows
  3156. the user to install a disc with a format that he only knows. When
  3157. the key combination is used, the format menu is entered which contains
  3158. information on the previous disc format. The user can change this data
  3159. using the cursor keys. Pressing return will install the new disc using
  3160. the new defined format.
  3161.  
  3162.  
  3163. CTRL+Keypad * (Line command)
  3164. ----------------------------
  3165. Enters the supervisor mode, so that you can issue *Commands.
  3166. Press Escape to return to the editor.
  3167. NOTE: You should not issue *Commands such as *Dedit or *Medit that cause
  3168.       the editors to entred. This re-entry will cause ARCTOOLS to
  3169.       loose track of data.
  3170.  
  3171.  
  3172. Right Cursor:
  3173. -------------
  3174. In the BINARY editor  : Move cursor right by one bit position.
  3175. In the HEX editor     : Move cursor right by one byte position.
  3176. In the WORD editor    : Move cursor right by one word (4 bytes).
  3177. In the NUMBER editor  : Inactive.
  3178. In the MNEMONIC editor: Show next display format flag status.
  3179. In the TEXT editor    : Move cursor right by one byte position.
  3180. In the BYTES editor   : Move cursor right by one byte position.
  3181.  
  3182.  
  3183. Left Cursor:
  3184. ------------
  3185. In the BINARY editor  : Move cursor left by one bit position.
  3186. In the HEX editor     : Move cursor left by one byte position.
  3187. In the WORD editor    : Move cursor left by one word (4 bytes).
  3188. In the NUMBER editor  : Inactive.
  3189. In the MNEMONIC editor: Show previous display format flag status.
  3190. In the TEXT editor    : Move cursor left by one byte position.
  3191. In the BYTES editor   : Move cursor left by one byte position.
  3192.  
  3193.  
  3194. Up Cursor:
  3195. ----------
  3196. This key is used to scroll the screen down. This decrements the current
  3197. highlighted address by:
  3198.  
  3199. In the BINARY editor  : 4 bytes.
  3200. In the HEX editor     : 16 bytes.
  3201. In the WORD editor    : 16 bytes.
  3202. In the NUMBER editor  : 4 bytes.
  3203. In the MNEMONIC editor: 4 bytes.
  3204. In the TEXT editor    : 64 bytes.
  3205. In the BYTES editor   : 8 bytes.
  3206.  
  3207.  
  3208. Down Cursor:
  3209. ------------
  3210. This key is used to scroll the screen up. This increments the current
  3211. highlighted address by:
  3212.  
  3213. In the BINARY editor  : 4 bytes.
  3214. In the HEX editor     : 16 bytes.
  3215. In the WORD editor    : 16 bytes.
  3216. In the NUMBER editor  : 4 bytes.
  3217. In the MNEMONIC editor: 4 bytes.
  3218. In the TEXT editor    : 64 bytes.
  3219. In the BYTES editor   : 8 bytes.
  3220.  
  3221.  
  3222. SHIFT+<Right Cursor> (Move cursor to rightmost position)
  3223. --------------------------------------------------------
  3224. This key commbination is used to move the cursor to the right most position
  3225. on the screen. However, in the Binary editor its used to move the cursor
  3226. to the right by one byte (8 bits).
  3227.  
  3228.  
  3229. SHIFT+<Left Cursor> (Move cursor to leftmost position)
  3230. ------------------------------------------------------
  3231. Move the cursor to the left most position on the screen. In the Binary
  3232. editor, this key combination is used to move the cursor to the left by
  3233. one byte (8 bits).
  3234.  
  3235.  
  3236. SHIFT+<Up Cursor> (Scroll down to previous screen)
  3237. --------------------------------------------------
  3238. This key combination is used to decrement the currently highlight address
  3239. by a value which depends on the type of editor;
  3240.  
  3241. In the BINARY editor  : 116 bytes.
  3242. In the HEX editor     : 464 bytes.
  3243. In the WORD editor    : 464 bytes.
  3244. In the NUMBER editor  : 116 bytes.
  3245. In the MNEMONIC editor: 116 bytes.
  3246. In the TEXT editor    : 1856 bytes.
  3247. In the BYTES editor   : 232 bytes.
  3248.  
  3249.  
  3250. SHIFT+<Down Cursor> (Scroll up to next screen)
  3251. ----------------------------------------------
  3252. This key combination is used to increment the currently highlight address
  3253. by a value which depends on the type of editor;
  3254.  
  3255. In the BINARY editor  : 116 bytes.
  3256. In the HEX editor     : 464 bytes.
  3257. In the WORD editor    : 464 bytes.
  3258. In the NUMBER editor  : 116 bytes.
  3259. In the MNEMONIC editor: 116 bytes.
  3260. In the TEXT editor    : 1856 bytes.
  3261. In the BYTES editor   : 232 bytes.
  3262.  
  3263. This key combination together with CTRL+<Up Cursor> provide a quick way of
  3264. scrolling through memory.
  3265.  
  3266.  
  3267. CTRL+<Right Cursor>
  3268. -------------------
  3269. In the Memory Editors: (Advance cursor to most right position)
  3270.  
  3271. This provides similar results to the SHIFT+<Right Cursor), except that in
  3272. the BINARY Editor, it advances the cursor to the most right position on the
  3273. screen.
  3274.  
  3275. In the Disc Editors: (Next sector)
  3276.  
  3277. Provide sector increment facility. If the sector has been modified, you
  3278. are offered to save the sector back to disc before you go to the next
  3279. sector.
  3280.  
  3281. CTRL+<Left Cursor>
  3282. ------------------
  3283. In the Memory Editors: (Advance cursor to most left position)
  3284.  
  3285. This provides similar results to the SHIFT+<Left Cursor), except that in
  3286. the BINARY Editor, it advances the cursor to the most left position on the
  3287. screen.
  3288.  
  3289. In the Disc Editors: (Previous sector)
  3290.  
  3291. Provide sector decrement facility. If the sector has been modified, you
  3292. are offered to save the sector back to disc before you go to the previous
  3293. sector.
  3294.  
  3295.  
  3296. CTRL+<Up Cursor>
  3297. ----------------
  3298. In the Memory Editors: (Go to memory page start address)
  3299.  
  3300. This provides a jump to the current memory page start address. If you are
  3301. already at the memory page start address, then the previous memory start
  3302. address is jumped to. The page size depends on the total ram in the
  3303. machine. In a 1 Mbytes machine, this is 8 Kbytes. In a 4 Mbytes machine
  3304. or higher, this is 32 Kbytes.
  3305.  
  3306. In the Disc Editor: (Go to previous disc track)
  3307.  
  3308. This provides a track decrement facility.
  3309.  
  3310.  
  3311. CTRL+<Down Cursor>
  3312. ------------------
  3313. In the Memory Editors: (Go to next memory page start address)
  3314.  
  3315. This provides a jump to the next memory page start address.
  3316. The page size depends on the total ram in the machine.
  3317.  
  3318. In the Disc Editor: (Go to next disc track)
  3319.  
  3320. This provides a track increment facility.
  3321.  
  3322.  
  3323. CTRL+SHIFT+<Up Cursor>
  3324. ----------------------
  3325. In the Memory Editors: (Go to current memory area start address)
  3326.  
  3327. This key combination provides a quick and easy method of moving from one
  3328. memory area to another. In addition if you are in the Relocatable Module
  3329. Area (RMA) or in the ROM area, then this key allows you to move to the
  3330. start of the module code. If you are already at the start of a memory area
  3331. or the start of a module code, this key will take you to the start address
  3332. of the previous memory area or module code.
  3333.  
  3334. In The Disc Editor: (Go to start of previous free disc map area)
  3335.  
  3336. Provide a facility to quickly identify non used area of the disc. This
  3337. where deleted files can be found!
  3338.  
  3339.  
  3340. CTRL+SHIFT+<Down Cursor>
  3341. ------------------------
  3342. In the Memory Editors: (Go to next memory area start address)
  3343.  
  3344. This key combination will take you to the start of the next memory area.
  3345. If the area contains modules, then it will take you to the start of the
  3346. next module. Using this key combination you can quickly browse through
  3347. all module without having to remember their start addresses.
  3348.  
  3349. In The Disc Editor: (Go to start of nex free disc map area)
  3350.  
  3351. Provide a facility to quickly identify non used area of the disc. This
  3352. where deleted files can be found!
  3353.  
  3354.  
  3355.                 The dis-assembler (Mnemonics Editor)
  3356.                 ====================================
  3357.  
  3358. This is the most powerfull memory editor provided by ARCTOOLS. It is an
  3359. essential tool when writing assembly code. The dis-assembler allows ARM,
  3360. FPU and co-processor instructions held in memory to be converted back into
  3361. the mnemonic form used by common ARM assemblers. The dis-assembler tends
  3362. to closely follow the BASIC assembler conventions.
  3363. ARCTOOLS does not use the built-in debugger dis-assembler SWI instruction
  3364. provided by RISC OS as this SWI has many limitations. ARCTOOLS provides
  3365. its own routines to disassemble ARM code.
  3366.  
  3367.  
  3368. The disassembler can be entered by typing:
  3369.  
  3370. *Medit <address> M     Enter the disassembler at <address>
  3371. *Medit <Label> M       Enter the disassembler at <Label>
  3372. *Medit M               Enter the disassembler at last visited address
  3373. *Medit                 Enter the disassembler at last visited address
  3374.                        if the disassembler was the last visited editor
  3375.  
  3376. or if already in any other editor pressing CTRL+M
  3377.  
  3378. Once entered, the disassembler screen contains one line per disassembled
  3379. instruction. Each display line contains five fields. The first field is
  3380. the memory address where the instruction is stored. This memory address
  3381. is always word aligned. The second field is the content of the memory
  3382. address in ASCII format. This is very useful, since some codes contain
  3383. text embedded between ARM instructions, an example is the OS SWI instruction
  3384. "OS_WriteS" which is always followed by a zero terminated, word aligned
  3385. text string. The third field is the memory word content displayed in
  3386. hexadecimal numbers. Not all assembly code is ARM or FPU instructions,
  3387. certain areas of memory contain data used as constants, data tables of
  3388. colour definitions, jump addresses as so on. In this case the third field
  3389. is the one of interest. The fourth and fifth fields are the data
  3390. interpreted as an ARM, FPU or co-processor instruction.
  3391. An instruction consists of two parts an OPCODE and an OPERAND. These
  3392. are fields four and five respectively.
  3393.  
  3394.  
  3395. The dis-assembler provides a large number of display formats which are
  3396. controlled by the user. The display formats are instant in effect.
  3397.  
  3398. How to change the dis-assembler display format?
  3399. ===============================================
  3400.  
  3401. When in the dis-assembler, the display format flags are shown at the
  3402. bottom of the screen, only one flag will be shown at any time, to
  3403. display the rest of the options flags, use the right and left cursor
  3404. keys. This will cycle through the whole set of flags, showing the
  3405. option number, its purpose and its status, for example:
  3406.  
  3407.  0:[SWI numbers              ]:[OFF]
  3408.  
  3409. This shows flag no. zero, which is the SWI numbers flag. The [OFF]
  3410. indicates that its currently OFF. To switch to ON, press CTRL + Insert
  3411. key combinations. This will cause the 'SWI numbers' flag to become
  3412. active causing all SWI instruction names to be replaced by numbers.
  3413. The effect is instant re-disassembly of all the code on the screen to
  3414. reflect the new flags status.
  3415.  
  3416. There are currently a total of 18 flags (0-17), these are as follows:
  3417.  
  3418.  0: SWI numbers.
  3419.     ON : All SWI instructions are shown as SWI numbers.
  3420.     OFF: All SWI instructions are shown as SWI names. [Default]
  3421.  
  3422.  1: Shifted immediate numbers.
  3423.     ON : Immediate numbers are shown as number<<shift. [Default]
  3424.     OFF: Immediate numbers shown the normal way.
  3425.  
  3426.     This flag allows easy interpretation of instructions that try to
  3427.     set or clear certain bits in a number, for example, it is much
  3428.     easier when you see the difference between these two instructions:
  3429.  
  3430.     BICNE   R0,R0,#&8000000
  3431.  
  3432.     BICNE   R0,R0,#1<<27
  3433.  
  3434.     It is very clear in the second line that the instruction is trying
  3435.     to clear bit 27 of R0.
  3436.     This conversion is carried out only for numbers that are shifted by
  3437.     more than 3 places and are higher than 255.
  3438.  
  3439.  2: Immediate number ---> ASCII chars.
  3440.     ON : Immediate numbers shown as ASCII characters when possible.
  3441.     OFF: No ASCII character display. [Default]
  3442.  
  3443.     When set to on, this flag allows immediate numbers in the ASCII
  3444.     character set to be shown as ASCII characters. For example:
  3445.  
  3446.     MOV  R1,#65   becomes   MOV  R1,#ASC"A"
  3447.  
  3448.  
  3449.  3: FEDA stack type.
  3450.     ON : Use the Full/Empty, Ascending/Descending stack type. [Default]
  3451.     OFF: Use the Increment/Decrement, Before/After stack type.
  3452.  
  3453.     This flag is used to select between the two types of stack notations.
  3454.     This notation is used with the LDM/STM type instructions.
  3455.  
  3456.     The most common stack type notation used by programmers is the
  3457.     FEDA type, for example:
  3458.  
  3459.     STMFD  R13!,{R14}
  3460.     LDMFD  R13!,{PC}^
  3461.  
  3462.     Using the IDBA notation, the above two instructions will be shown
  3463.     as:
  3464.  
  3465.     STMDB  R13!,{R14}
  3466.     LDMIA  R13!,{PC}^
  3467.  
  3468.  4: PC relative Load/Store.
  3469.     ON : PC relative addressing notation is shown. [Default]
  3470.     OFF: PC relative addressing display switched off.
  3471.  
  3472.     When this flag is on, the following instruction:
  3473.  
  3474.     LDR  R0,[PC,#12], becomes   LDR R0,address
  3475.  
  3476.  5: SWI names quotes.
  3477.     ON : All SWI names are enclosed in quotation marks.
  3478.     OFF: All SWI names are displayed without quotation marks. [Default]
  3479.  
  3480.  6: HS/LO condition codes.
  3481.     ON : The CC and CS condition codes are replaced by HS and LO. [Default]
  3482.     OFF: The condition codes CC and CS are used.
  3483.  
  3484.  7: ADR directive.
  3485.     ON : The ADR directive is used. [Default]
  3486.     OFF: The ADR directive is not used.
  3487.  
  3488.     When this flag is on, any instructions which use reference to the
  3489.     PC with ADD and SUB opcodes together with immediate numbers are
  3490.     replaced by the ADR directive.
  3491.  
  3492.  8: LSL/LSR ---> */DIV.
  3493.     ON : LSL and LSR shifts are converted into * and DIV keywords.
  3494.     OFF: Shifts using LSL and LSR are displayed as normal. [Default]
  3495.  
  3496.     When on, this flag allows the display of instructions using the
  3497.     LSL and LSR to be shown as * (multiply) and DIV (divide)
  3498.     instructions. Examples:
  3499.  
  3500.     MOV  R0,R1,LSL #2     becomes    MOV  R0,R1*4
  3501.     ADD  R1,R2,R3,LSR #3  becomes    ADD  R1,R2,R3 DIV 8
  3502.  
  3503.     Remember that the single-line dis-assembler accepts these new
  3504.     keywords.
  3505.  
  3506.  9: Decimal numbers only.
  3507.     ON : All immediate numbers are shown as decimal numbers.
  3508.     OFF: All immediate numbers are shown in the default format. [Default]
  3509.  
  3510.     When on, this flag causes all immediate numbers to be shown as
  3511.     decimal numbers. This does not affect the the display of addresses
  3512.     used in instructions such as B and BL, as these are always shown
  3513.     as hexadecimal numbers.
  3514.  
  3515. 10: Signed decimal numbers.
  3516.     ON : All decimal numbers are shown as signed numbers.
  3517.     OFF: All decimal numbers are shown as unsigned numbers. [Default]
  3518.  
  3519.     For this flag to be effective, flag no. 9 (Decimal numbers only) must
  3520.     also be on.
  3521.  
  3522. 11: MVN/CMN/CNF ---> MOV/CMP/CMF.
  3523.     ON : Allow conversion of above instruction.
  3524.     OFF: Switch off conversion. [Default]
  3525.  
  3526.     When on, this flag allows the MVN instruction to be shown as MOV,
  3527.     CMN as CMP, and CNF as CMF. For example:
  3528.  
  3529.     MVN  R0,#1  becomes  MOV  R0,#-2
  3530.     CMN  R0,#1  becomes  CMP  R0,#-1
  3531.  
  3532.     Do not format to turn the 'Decimal numbers only' and the 'Signed
  3533.     decimal numbers' flags on to see the result in signed decimal numbers.
  3534.  
  3535. 12: Co-processor instructions.
  3536.     ON : All co-processor instructions disassembled. [Default]
  3537.    !OFF: no co-processor instructions shown.
  3538.  
  3539.     This flag must be on to allow both the co-processor and FPU instructions
  3540.     to be disassembled.
  3541.     When set to OFF, all co-processor instructions are replaced by the
  3542.     message: "Co-processor instruction", including all FPU instructions.
  3543.  
  3544. 13: FPU instructions.
  3545.     ON : All Floating Point co-processor instructions shown. [Default]
  3546.     OFF: No FPU instruction disassembled.
  3547.  
  3548.     To disassemble FPU instructions both the 'FPU instructions' and the
  3549.     'Co-processor instructions' flags must set to ON. If the 'FPU
  3550.     instructions' flag is set to OFF, then all FPU instructions will be
  3551.     disassembled as co-processor instructions.
  3552.  
  3553. 14: Power multiply.
  3554.     ON : Use the 'power multiply' notation.
  3555.     OFF: Use normal display. [Default]
  3556.  
  3557.     When on, this flag allows the following conversion to take place:
  3558.  
  3559.     MOV R0,R1,LSL #1     becomes   MOV  R0,R1*2
  3560.     ADD R0,R1,R1,LSL #2  becomes   MOV  R0,R1*3
  3561.     RSB R0,R1,R1,LSL #3  becomes   MOV  R0,R1*7
  3562.     SUB R0,R1,R1,LSL #2  becomes   MOV  R0,R1*-3    
  3563.     
  3564. 15: Labels and remarks.
  3565.     ON : Allows any defined labels and remarks to be shown. [Default]
  3566.     OFF: Disables labels and remarks display.
  3567.  
  3568. 16: Long ADR directive.
  3569.     ON : Disassembles the ADRL directive. [Default]
  3570.     OFF: Disables ADRL directive disassembly.
  3571.  
  3572. 17: Show bad instructions.
  3573.     ON : Bad instructions are flagged. [Default]
  3574.     OFF: Bad instruction flagging disabled.
  3575.  
  3576.     Bad instructions are those which are (normally) not created by
  3577.     assemblers. They are normal instructions which the CPU will in
  3578.     many ways accept but have certain bit set or clear. ARCTOOLS
  3579.     defines the following as Bad instructions:
  3580.  
  3581.     1. Bad MUL: Bits set.
  3582.  
  3583.        This is a MUL or MLA instruction with either or both bits 5 and 6 set.
  3584.  
  3585.     2. Bad MUL: Rd=PC.
  3586.  
  3587.        This is a MUL or MLA instruction with the destination register equal
  3588.        to the PC (R15).
  3589.  
  3590.     3. Bad MUL: Rd=Rm
  3591.  
  3592.        This is a MUL or MLA instruction with the Destination Register set
  3593.        to the same number as the Rm register.
  3594.  
  3595.     4. Bad MUL: Rn set.
  3596.  
  3597.        This is a MUL instruction with bits 12 to 15, used only in the MLA
  3598.        instruction as the accumulate instruction number, not clear.
  3599.  
  3600.     5. Bad Comparison.
  3601.  
  3602.        This is a comparison instruction (CMP, CMN, TST or TEQ) with the
  3603.        S-bit (bit 20) clear. All comparison instructions must have the
  3604.        set condition code bit set to function as expected.
  3605.  
  3606.     6. Bad MOV/MVN.
  3607.  
  3608.        This is a MOV or MVN instruction, with any of bits 16 to 19 set.
  3609.        The MOV and MVN instructions do not have <Rn> register. The
  3610.        <Rn> register field must be zero.
  3611.  
  3612.     7. Bad shift.
  3613.  
  3614.        This is a shift operation of LSR or ASR with the shift number
  3615.        equal to zero.
  3616.  
  3617.     
  3618.  
  3619. Colours used in the dis-assembler:
  3620. ==================================
  3621.  
  3622. The dis-assembler uses colors to provide an easy way of identifying
  3623. pieces of code or sub-routines.
  3624.  
  3625. The colors used are:
  3626.  
  3627.  - Orange :  Branch instructions and addresses.
  3628.  - Red    :  Undefined and Bad instructions.
  3629.  - Magenta:  Co-processor instructions.
  3630.  - Cyan   :  FPU instructions and ARM3 co-processor instructions.
  3631.  - Brown  :  STM and LDM instructions.
  3632.  - Yellow :  SWI instructions, labels and remarks.
  3633.  
  3634.     
  3635.  
  3636.  
  3637.  
  3638.                        The Single Line Assembler
  3639.                        =========================
  3640.  
  3641. The single line assembler is built into both memory and disc Mnemonic
  3642. editors or dis-assemblers.
  3643. To enter the single line assembler simply press CTRL+M when in any
  3644. of the other editors. This automatically selects the Mnemonic editor.
  3645. The editor in this mode will try its best to interpret the contents
  3646. of memory or disc and produce the corresponding instruction.
  3647. The Mnemonic editor or disassembler can disassemble all instructions.
  3648.  
  3649. There are 3 types of instructions:
  3650. 1. ARM Instructions
  3651. 2. Floating Point Instructions
  3652. 3. Co-processor Instructions
  3653.  
  3654. The dis-assembler will disassemble all of the above types of instructions.
  3655. The Single-Line_Assembler will assemble all of the above instructions, and
  3656. hence it covers all possible instructions.
  3657.  
  3658. There are some Undefined instructions, and are at the moment of two types:
  3659.  
  3660. 1. Undefined ARM Instructions
  3661. 2. Undefined FPU Instructions
  3662.  
  3663. These are referred to by Acorn as Reserved or Undefined instructions.
  3664.  
  3665. There are no illegal Co-processor instructions. All 16 possible co-
  3666. processor instructions will be assembled and disassembled!!!
  3667.  
  3668. Co-processors are numbered 0-15. Number 1 being the Floating point
  3669. co-processor. Therefore, you can assemble FPU instructions using
  3670. co-processor instruction with the co-processor number set to 1 or
  3671. simply use the best and logical way: using FPU instructions.
  3672.  
  3673. This manual will not teach how to write assembly code. And the following
  3674. information assumes that you are familiar with both the ARM and FPU
  3675. instruction sets.
  3676.  
  3677. How to enter the Single-Line-Assembler?
  3678. ======================================
  3679.  
  3680. In the Mnemonic editor by pressing the first character of your new line.
  3681. This causes the message "Enter Instruction:" to be displayed followed
  3682. by the character typed. You can now continue typing the instruction.
  3683. Pressing Return, Cursor Up or Cursor Down causes ARCTOOLS to assemble
  3684. the new line of code. If the line of code is acceptable the assembled
  3685. opcode is put into memory and the memory cursor advanced in a direction
  3686. determined by the terminating key.
  3687. If the terminating key was Cursor Up the memory cursor moves up. Return,
  3688. Enter or Cursor Down keys causes it to move down to the next memory address.
  3689.  
  3690.  
  3691. Small changes to existing code:
  3692. ===============================
  3693.  
  3694. You may sometimes want to change only a small part of the Instruction
  3695. already displayed, possibly the condition code part or the "S" suffix.
  3696. To do so, press CTRL+Return. This will enter the Single-Line-Assembler
  3697. with the cursor position on the first character of the line. You can
  3698. now move the cursor left or right and modify the line.
  3699.  
  3700. Example:
  3701. Instruction at Cursor is:  MOVS PC,R14
  3702. Target Instruction is: MOV PC,R14
  3703. Action: Press CTRL+Return, move cursor right to the letter "S", press
  3704. the space key, Press return.
  3705.  
  3706. If the assembler could not assemble the code for any reason, an error
  3707. message is displayed for a short time (time delay can be overridden by pressing
  3708. the ESCAPE key). After this time delay, you are put back on the same
  3709. line of text you have typed with the cursor at the character which
  3710. causes the error. This makes it easy for you to identify the part that
  3711. caused the error. You can now correct the error or press Escape to exit
  3712. the Single-Line Assembler.
  3713.  
  3714. At any time, pressing the Escape key exits the assembler without assembling
  3715. the new line of code.
  3716.  
  3717. The single line assembler will ignore any irrelevant text or data after
  3718. the instruction. The exception is when assembling immediate numbers or
  3719. reference to addresses. This is because in these two cases the Operating
  3720. System 'EVAL' function is used which tries to evaluate the whole string
  3721. of text.
  3722.  
  3723.  
  3724.  
  3725.  
  3726. HOW TO USE THE SINGLE-LINE ASSEMBLER
  3727. ====================================
  3728.  
  3729. The single-line assembler is compatible with the BBC BASIC's assembler.
  3730. There are however exceptions. Being only a single line assembler, you
  3731. can not use variables, except labels if already defined, as in a fully
  3732. blown assembler.
  3733. It can be generally said that any instruction that the dis-assembler
  3734. can display, the assembler will accept.
  3735. If you are familiar with any ARM assembler then you will find no problems
  3736. with this assembler.
  3737. The use of the FPU instructions is described in the Programmers Reference
  3738. Manual. The co-processors instructions set is describes in the excellent
  3739. book " ARM Assembly Language programming" by Peter Cockerell.
  3740.  
  3741.  
  3742.                    The Single-Line-Assembler Features:
  3743.                    ===================================
  3744.  1. Assemble all ARM instructions.
  3745.  
  3746.  2. Assemble all FPU instructions.
  3747.  
  3748.  3. Assemble all co-processor instructions.
  3749.  
  3750.  4. Text entered is case insensitive. (except SWI name).
  3751.  
  3752.  5. Automatic use of complement instructions:
  3753.     MOV  R0,#-1    will be assembled as  MVN  R0,#0
  3754.     ADD  R0,R1,#-2 will be assembled as  SUB  R0,R1,#2
  3755.     The complement instruction conversion will be carried out with the
  3756.     following instructions:
  3757.     MOV-MVN, BIC-AND, ADD-SUB, ADC-SBC, CMP/CMN
  3758.     The assembler will try to convert into a complement instruction if
  3759.     the immediate number can not be encoded into the instruction. If it
  3760.     fails the second time it will generate an error.
  3761.  
  3762.  6. Accepts PC-relative addressing.
  3763.     example:  LDR   R0,&20000
  3764.               STRB  R1,&21000
  3765.               STFS  F0,&10000
  3766.     The offset of the address given in the instruction should not be more
  3767.     than 4095 bytes from the current memory address for ARM instructions,
  3768.     and 1020 for FPU instructions. The FPU offset address must be word-
  3769.     aligned.
  3770.  
  3771.  7. Accepts the BBC BASIC's ADR directive.
  3772.     Limits imposed by the use of the ADR directive are the same as those
  3773.     in ARM BBC BASIC.
  3774.  
  3775.  8. Accepts the ADRL (long ADR) directive. Creating two instructions to
  3776.     cover an offset of 64 Kbytes.
  3777.     Note: An error message will be generated if you try to assemble the
  3778.           ADRL directive at the end of a memory boundary.
  3779.  
  3780.  9. Accepts the BBC BASIC's ASC keyword.
  3781.     example:SUB   R0,R0,#ASC"0"   equivalent to SUB  R0,R0,#48
  3782.             CMP   R2,#ASC" "      equivalent to CMP  R0,#32
  3783.  
  3784.             An alternative method is to omit the "ASC" word.
  3785.  
  3786.     Example: MOV   R0," "    equivalent to MOV  R0,#ASC" "
  3787.              MOV   R0,""     same as above
  3788.              MOV   R0,"""    equivalent to MOV  R0,#34
  3789.  
  3790. 10. Accepts many forms of Software Instructions.
  3791.     Example: SWINE   "OS_WriteC"
  3792.              SWI     XOS_Write0
  3793.              SWI     0
  3794.              SWIPL   256+7
  3795.              SWI     "OS_WriteI"+7
  3796.              SWI     256+ASC"0"
  3797.              SWI     256+"0"
  3798.              SWI     2+1      equivalent to SWI  3
  3799.              SWI     OS_WriteI+ASC"a"
  3800.              SWI     256+""
  3801.  
  3802.   Note: There are Software Instructions that can not be assembled.
  3803.         They are:
  3804.         "User", "OS_Undefined"
  3805.         This is because, these two SWIs cover a wide range of SWI
  3806.         instruction numbers, and hence The Operating System can
  3807.         not tell which number you want.
  3808.  
  3809. 11. Ignores irrelevant spaces in entered instruction.
  3810.     Example: MOVR0,R1           = MOV R0,R1 
  3811.              ADDR2,R5,R3        = ADD R2,R5,R3
  3812.              andR3,R4,R2LSL#2   = and R3,R4,R2,LSL #2
  3813.     The exception is with the 'SWI' opcode as a space between the opcode
  3814.     and operand is necessary
  3815.  
  3816. 12. Understands the following for register numbers:
  3817.     ARM Instructions         : (0-14,15|PC) or (R0-R14,R15|PC)
  3818.     FPU Instructions         : (0-7) or (F0-F7)
  3819.     Co-processor Instructions: (0-15) or (C0-C15)
  3820.     ARM3 co-processor        : (0-5) or (C0-C5) or register name:
  3821.                                ID, Flush, Control, Cacheable,
  3822.                                Updateable, Disruptive.
  3823.  
  3824. 13. Uses the OS 'EVAL' function to evaluate integers, so any mathematical
  3825.     expression is allowed in immediate numbers.
  3826.     Examples:AND     R2,R3,#-2
  3827.              BICS    PC,R14,#1<<29
  3828.              ORREQ   R1,R2,#-1<<20
  3829.              MOV     R0,#NOT 1
  3830.              ADD     R3,R2,#30+4*25
  3831.              SUB     R0,R0,#1 OR (1<<5)
  3832.              SUBNE   R1,R2,#ASC"0"
  3833.              ADDPL   R2,R2,"a"
  3834.  
  3835. 14. Understands power multiply instructions.
  3836.     Example: MOV  R0,R1*2    becomes   MOV  R0,R1,LSL #1
  3837.              MOV  R0,R1*3    becomes   ADD  R0,R1,R1,LSL #2
  3838.              MOV  R0,R1*7    becomes   RSB  R0,R1,R1,LSL #3
  3839.              MOV  R0,R1*-3   becomes   SUB  R0,R1,R1,LSL #2
  3840.  
  3841. 15. Understands '*' and 'DIV' as alternatives for 'LSL' and 'LSR'.
  3842.     Example: MOV  R0,R1*4     becomes   MOV  R0,R1,LSL #2
  3843.              ADD  R0,R1,R2*32 becomes   ADD  R0,R1,R2 LSL #5
  3844.              MOV  R0,R1 DIV 8 becomes   MOV  R0,R1,LSR #3
  3845.  
  3846. 16. Accepts labels previously defined in place of any reference to
  3847.     a memory address.
  3848.  
  3849.  
  3850. 17. Assembles the new ARM3 SWP instruction.
  3851.  
  3852. 18. Assembles the ARM3 cache control instructions.
  3853.  
  3854. The Single-Line Assembler conventions:
  3855. ======================================
  3856.  
  3857. 1. The instruction  STR  R0,[R1] is assembled into STR R0,[R1,#0]
  3858. 2. The instruction  STR  R0,[R1]! is assembled into STR R0,[R1,#0]!
  3859. 3. The instruction  STRT  R0,[R1] is assembled into STRT R0,[R1],#0
  3860.  
  3861.  
  3862. The single-line assembler errors:
  3863. =================================
  3864.  
  3865.  1. Unknown opcode
  3866.  2. Bad shift
  3867.  3. Bad multiply, <Rd>=PC
  3868.  4. Bad multiply, <Rn>=<Rd>
  3869.  5. Bad register
  3870.  6. Bad ASCII
  3871.  7. Missing ' '    : This is produced when an expected char is missing.
  3872.  8. Bad number
  3873.  9. Bad address/label
  3874. 10. Can't encode number
  3875. 11. Non aligned address
  3876. 12. Bad operation
  3877. 13. Bad immediate operand
  3878. 14. No 'T' with pre-indexed or PC-relative addressing
  3879. 15. Bad offset
  3880. 16. Bad Co-processor operation
  3881. 17. Precision needed
  3882.  
  3883.  
  3884.  
  3885.                     Calling the assembler from BASIC
  3886.                     ================================
  3887.  
  3888.  ARCTOOLS provides a single SWI which can be used from your own BASIC
  3889.  assembly code. This allows assembly of all FPU instructions, all
  3890.  co-processor instructions, the new ARM3 SWP instruction and all Cache
  3891.  control instructions, from within the BASIC assembler.
  3892.  
  3893.  To allow this you need to add a simple function in your BASIC program
  3894.  which will be called from within the assembly lines.
  3895.  
  3896.  Here is an example of the BASIC function:
  3897.  =========================================
  3898.  
  3899.  DEF FNass(A$)
  3900.  SYS "ARCTOOLS_Assemble",A$,P% TO !P% : P%+=4 : =TRUE
  3901.  
  3902.  
  3903.  The following is an example of the use of the cache control instruction
  3904.  assembly. Two routines are provided, one to switch ON the cache, and the
  3905.  other to switch it OFF.
  3906.  NOTE: The example given will only work on ARM 3 processors.
  3907.  
  3908.  DIM code 1000
  3909.  FOR pass= 0 TO 2 STEP 2
  3910.  P%=code
  3911.  [OPT pass
  3912.  
  3913.  .CacheON
  3914.  STMFD  R13!,{R0,R14}           ;Push regs on the stack
  3915.  MOV    R0,#3                   ;Value to write into cache control reg
  3916.  B      Do_It
  3917.  .CacheOFF
  3918.  STMFD  R13!,{R0,R14}           ;Push regs on the stack
  3919.  MOV    R0,#2                   ;Value to write into cache control reg
  3920.  .Do_It
  3921.  SWI    "XOS_EnterOS"           ;Enter SPV mode, so we can write to cache
  3922.  FNass(" CHSW  R0,Control")     ;Write R0 into cache 'Control' register
  3923.  TEQP   PC,#0                   ;Return to user mode
  3924.  LDMFD  R13!,{R0,PC}^           ;Pull regs and preserve flags
  3925.  ]
  3926.  NEXT
  3927.  END
  3928.  
  3929.  The above example demonstrates the use of ARCTOOLS single-line assembler
  3930.  from a BASIC program. Of course, any valid instruction that ARCTOOLS
  3931.  understands can be assembled. See above for full assembler syntax.
  3932.  There are however some limitations:
  3933.  
  3934.  1. You should not use variables when ARCTOOLS_Assemble SWI.
  3935.  2. You should not call the ARCTOOLS ADR directive with a label or variable.
  3936.  3. You should not call ARCTOOLS ADRL directive.
  3937.  
  3938.  
  3939.  
  3940.          Using the dis-assembler to recover lost source code files
  3941.          =========================================================
  3942.  
  3943.    This section will be given in detail in the next version of ARCTOOLS.
  3944.    If your are an experienced ARM programmer, you will have no problem
  3945.    using the dis-assembler together with the automatic labelling feature
  3946.    and the *Mdump command to get back your lost files.
  3947.  
  3948.    Next versions of ARCTOOLS will make the conversion process as
  3949.    intelligent as possible. This will include automatic Modules
  3950.    conversions. A simple of way of marking memory areas as Data items
  3951.    or strings, so that these will be converted into DCB, DCD or EQUS
  3952.    equivalents.
  3953.  
  3954.    The current version of ARCTOOLS allows the instruction "SWI OS_WriteS",
  3955.    when dumped to the screen to be followed by the string which would be
  3956.    printed. The string is shown in EQUS and DCB keywords, followed by the
  3957.    keyword 'ALIGN'.
  3958.  
  3959.                  ARM 3 instructions assembly and disassembly
  3960.                  ===========================================
  3961.  
  3962.  The SWP instruction:
  3963.  ====================
  3964.  
  3965.  The SWP instruction is used to swap a byte or word between register
  3966.  and memory. It is used as a form of LDR/STR in multi-processor installation.
  3967.  During the execution of this instruction, the bus interface LOCK signal
  3968.  is asserted so that other processors will not gain access to the bus.
  3969.  
  3970.  The instruction syntax is:
  3971.  
  3972.  SWP<cond><B>  Rd,Rm,[Rn]
  3973.  
  3974.  The SWP instruction performs the following operations:
  3975.  1. Copy the content of <Rn> address into <Rd>,
  3976.  2. Store <Rm> into <Rn> address.
  3977.  
  3978.  The SWP instruction is only executed in a supervisor mode.
  3979.  
  3980.  ARCTOOLS will assemble and disassemble the SWP instruction. Examples are:
  3981.  
  3982.    SWPNE   R0,R3,[R10]
  3983.    SWPB    R1,R0,[R2]
  3984.    SWPPLB  R0,R1,[R7]
  3985.  
  3986.  
  3987.  
  3988.  The cache control register operations:
  3989.  ======================================
  3990.  ARM 3 processors contain within them a cache memory. The cache caches
  3991.  virtually addressed data. For efficiency the cache does not cache
  3992.  everything. To control the various operations of the cache, 6 control
  3993.  registers are provided. These are:
  3994.  
  3995.  0 : ID register
  3996.  1 : Flush register
  3997.  2 : Control register
  3998.  3 : Cacheable register
  3999.  4 : Updateable register
  4000.  5 : Disruptive register
  4001.  
  4002.  The cache control instructions use the co-processor register transfer
  4003.  instructions (MRC and MCR instructions) with the co-processor number set
  4004.  to 15.
  4005.  Two instructions are provided to communicate with the cache registers;
  4006.  the MRC instruction which copies the content of the ARM register to the
  4007.  cache control register and the MCR which copies the content of the cache
  4008.  control register to the ARM register.
  4009.  
  4010.  ARCTOOLS can assemble and disassemble all co-processor instructions and
  4011.  hence communication with the cache can be performed using the MCR and MRC
  4012.  instructions. The MCR and MRC instructions syntax is very complex and
  4013.  difficult to remember, example:
  4014.  
  4015.  To read the cache ID register into R4:
  4016.  
  4017.  MCR  Cp#15,Op#0,R4,C0,C0,0
  4018.  
  4019.  this can be abbreviated into:
  4020.  
  4021.  MCR  15,0,R4,0,0,0
  4022.  
  4023.  However, ARCTOOLS provides a new instrcution syntax to handle these
  4024.  instrcutions.
  4025.  
  4026.  Instruction sysntax:  CSHR<cond>  Rd,Cx
  4027.  ====================  CSHW<cond>  Rd,Cx
  4028.  
  4029.  where:
  4030.        CSHR : opcode to read the cache register into ARM register.
  4031.        CSHW : opcode to write the ARM register into the cache register.
  4032.        Rd   : ARM register R0 - R15
  4033.        Cx   : cache control register C0 to C5.
  4034.  
  4035.  ARCTOOLS also understands cache register name so that:
  4036.  
  4037.  C0 = ID
  4038.  C1 = Flush
  4039.  C2 = Control
  4040.  C3 = Cacheable
  4041.  C4 = Updateable
  4042.  C5 = Disruptive
  4043.  
  4044.  Examples:
  4045.  =========
  4046.  
  4047.  CSHREQ  R4,C0                 ;Read cache ID register into R4.
  4048.  CSHR    R0,Cacheable          ;Read cacheable register into R0.
  4049.  CSHW    R7,Control            ;Write R7 into cache control register.
  4050.  
  4051.  Note: The cache control insructions are only executed in supervisor mode.
  4052.        In other processor modes, these instructions will fail as 'Undefined
  4053.        instructions'!!
  4054.